Adopting a pet is not only an emotional decision. A lasting relationship also depends on time, space, household composition, energy, previous experience and the individual needs of the animal.
VincuPet explores how an in-browser recommendation system can organize family-to-pet compatibility signals without pretending to replace the human assessment performed by adopters, shelters and animal-care professionals.
The project connects applied artificial intelligence with software engineering: structured data, modular responsibilities, background model training, transparent limitations and a user experience designed around responsible adoption.
VincuPet is an educational portfolio evolution built from a recommendation system reproduced during a postgraduate Software Engineering with Applied AI class.
- A meaningful recommendation domain: products and purchases become families, adoptable pets and observed affinities.
- Training outside the main UI thread: TensorFlow.js runs inside a Web Worker, keeping the interface responsive.
- Individual context: species, breed, size, age, energy and observed behavior are presented separately.
- Responsible framing: breed is context, not a deterministic prediction of personality.
- Local-first data: demonstration profiles and interactions remain in the browser session.
- Honest engineering: training accuracy is shown as a learning diagnostic, not as proof that the model generalizes.
The animation below shows a real browser session: a family profile is selected, the pet catalog is reordered from the learned affinities and a new affinity is demonstrated.
Responsive experience
- Fictional family profiles and their previously observed pet affinities are loaded from local JSON.
- Pet attributes are normalized and encoded as numerical features.
- Family and pet vectors are combined into supervised training pairs.
- A dense neural network is trained with TensorFlow.js inside a Web Worker.
- The selected family is paired with every available pet.
- The model produces scores used to reorder the catalog.
The current dataset is intentionally small and educational. Hyperparameters, feature weights and training epochs are didactic choices, not universally optimal values.
flowchart LR
Families["Family profiles"] --> Worker["TensorFlow.js Web Worker"]
Pets["Pet profiles"] --> Worker
Worker --> Model["Dense neural network"]
Selection["Selected family"] --> Model
Model --> Ranking["Compatibility ranking"]
Ranking --> UI["Browser interface"]
The application currently follows a compact MVC-inspired structure:
| Area | Responsibility |
|---|---|
service |
Loads local data and manages session-scoped family state |
controller |
Coordinates user actions, events, model training and ranking |
view |
Renders families, pets, training progress and charts |
events |
Decouples browser interactions through an event bus |
workers |
Encodes data, trains the model and performs inference off-thread |
Read the architecture notes for the current boundaries, inherited terminology and planned domain refactoring.
The automated suite currently protects:
- product identity and responsible-adoption messaging;
- the presence of family and pet datasets;
- breed and observed behavior in every pet profile;
- transparent academic and evolution credits;
- the complete bilingual GitHub presentation contract.
npm testExpected result: 8 passing tests using Node.js' native test runner.
Requirements:
- a modern browser;
- Node.js 20 or newer;
- internet access on first load for TensorFlow.js, TFVis and Bootstrap assets.
git clone https://github.com/claudneysessa/vincupet.git
cd vincupet
npm ci
npm startOpen http://localhost:3000.
| Technology | Role in the project |
|---|---|
| HTML5 | Semantic structure, forms, dialog and accessibility contracts |
| CSS3 | Responsive visual system and component styling |
| JavaScript | Application implementation with native ES Modules |
| TensorFlow.js 4.22 | In-browser neural-network training and inference |
| TFVis 1.5.1 | Training-loss and accuracy visualization |
| Web Workers | Background model training without blocking the interface |
| Bootstrap 5 | Layout primitives and accessible component foundations |
| Node.js test runner | Dependency-free automated tests |
| GitHub Actions | Continuous integration |
| GitHub Pages | Free HTTPS hosting for the browser application |
- VincuPet does not collect real adoption data.
- The included families and pets are fictional demonstration records.
- Session interactions are stored locally in
sessionStorage. - Training and inference happen in the browser.
- The system does not approve, reject or finalize adoptions.
- A real-world version would require professional review, representative data, bias analysis, safeguarding rules and shelter-specific adoption policies.
VincuPet intentionally starts with a small, understandable browser-first experiment. Its current boundaries point directly to the next engineering gains:
- A compact fictional dataset makes the full learning flow easy to inspect, while a future evaluation dataset will enable stronger generalization checks.
- Neural ranking demonstrates applied TensorFlow.js, while a rule-based baseline will create a clearer reference for comparison and explanation.
- Local processing favors privacy and instant experimentation, while production adoption workflows would require reviewed data governance and institution-specific safeguards.
- The academic foundation accelerated learning, while the ongoing domain refactoring is turning inherited terminology into a cohesive pet-adoption language.
These boundaries are documented as engineering checkpoints, not hidden as finished capabilities:
- The dataset is too small to demonstrate real-world generalization.
- Accuracy is measured on training data; there is no validation split yet.
- Historical affinities can leak target information into family representations.
- The neural ranking is not yet compared with a transparent rule-based baseline.
- Internal class names inherited from the academic exercise still use
User,ProductandPurchaseterminology. - Compatibility reasons and uncertainty are not yet shown in each card.
- Transformed the academic commerce example into a responsible-adoption domain.
- Created original family and pet profiles with breed, energy and observed behavior represented as separate context.
- Rebuilt the identity, interface and narrative around explainable compatibility.
- Kept TensorFlow.js training outside the main UI thread through a Web Worker.
- Added responsive design, real demonstration media, bilingual documentation, automated tests and continuous integration.
- Made authorship, academic foundation, privacy and model boundaries explicit.
- Refactor inherited names to
Family,PetandAffinity. - Add a rule-based baseline and compare it with the neural ranking.
- Introduce train/validation separation and suitable ranking metrics.
- Display compatibility factors, trade-offs and uncertainty.
- Add family-profile editing without collecting personal data.
- Replace symbolic pet illustrations with properly licensed media.
- Expand automated browser and accessibility checks.
The initial recommendation-system structure was reproduced as an academic exercise during postgraduate study. VincuPet is a portfolio evolution that changes the product domain, fictional dataset, identity, visual presentation, responsible-adoption framing, documentation and quality workflow.
The evolution is developed by Claudney Sarti Sessa, Systems Analyst and Information Systems graduate, with postgraduate studies in Big Data & Analytics and Software Engineering, currently specializing in Software Engineering with Applied AI.
Third-party libraries, platforms and study references remain the property of their respective authors. The repository will not claim exclusive authorship over the reproduced academic foundation.