# salman-sensei/purrfect-care architecture

> Architecture diagram of the GitHub repository salman-sensei/purrfect-care, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/salman-sensei/purrfect-care
- Repository: https://github.com/salman-sensei/purrfect-care

## Overview

1. **Overall shape**
   - This is a split **MERN-style monorepo** with a React/Vite frontend and a Node/Express backend.
   - The frontend is a client-side SPA; the backend is a JSON REST API.
   - Persistent state lives in **MongoDB Atlas** through **Mongoose** models.

2. **Primary boundary**
   - The cleanest architecture boundary is between **frontend UI/state** and **backend domain/API logic**.
   - The frontend never talks directly to the database; all CRUD flows go through `frontend/src/services/api.js` into Express routes under `backend/routes/*`.

3. **Backend entry and infrastructure**
   - `backend/server.js` is the API bootstrap: Express app setup, middleware, route mounting, and DB connection wiring.
   - `backend/config/db.js` handles the MongoDB connection.
   - The backend is deployed separately from the frontend, so the API must be reachable over HTTP and is configured via environment variables like `MONGO_URI`, `JWT_SECRET`, and `CLIENT_URL`.

4. **Authentication subsystem**
   - Auth is centered on `backend/models/User.js`, `backend/controllers/authController.js`, `backend/routes/authRoutes.js`, and `backend/middleware/authMiddleware.js`.
   - The system uses **JWT-based stateless auth** with protected routes guarded by middleware.
   - On the frontend, `frontend/src/context/AuthContext.jsx`, `frontend/src/services/auth.js`, and `frontend/src/components/ProtectedRoute.jsx` manage session state, token persistence, and route gating.

5. **Core domain data model**
   - The main user-owned entities are:
     - **Cats**: `backend/models/Cat.js`
     - **Tasks**: `backend/models/Task.js`
     - **Vet records**: `backend/models/VetRecord.js`
   - These models imply a per-user, multi-entity care management system where each authenticated user owns multiple cats and related records.

6. **Cat management subsystem**
   - Cat CRUD flows run through `catRoutes.js` and `catController.js`.
   - Frontend pages and components such as `CatsPage.jsx`, `CatProfilePage.jsx`, `CatForm.jsx`, `CatCard.jsx`, and `useCats.js` handle listing, creation, editing, and display.
   - The README’s “cat profiles” feature maps directly to this subsystem and includes profile details, color themes, and tabbed views.

7. **Daily task / checklist subsystem**
   - Task CRUD and completion toggling are managed by `taskRoutes.js` and `taskController.js`.
   - The frontend uses `ChecklistPage.jsx`, `TaskForm.jsx`, `TaskCard.jsx`, and `useTasks.js`.
   - The main data flow here is: fetch tasks filtered by date/cat, toggle completion, and compute progress for the dashboard’s “Purr Level™” style status.

8. **Vet records subsystem**
   - Vet visit management is implemented in `vetRoutes.js` and `vetController.js`, backed by `VetRecord.js`.
   - The UI side includes `VetRecordsPage.jsx`, `VetForm.jsx`, and `useVetRecords.js`.
   - This subsystem supports visit-type classification, reminder-oriented fields like next visit date, and dashboard summaries for upcoming appointments.

9. **Dashboard aggregation layer**
   - `DashboardPage.jsx` acts as a cross-domain summary view rather than a separate data source.
   - It likely aggregates cats, tasks, and vet records from multiple API calls to produce widgets like greeting, spotlight card, stats counters, today’s tasks, and upcoming reminders.
   - Architecturally, this is the main read-composition surface of the app.

10. **Assistant / recommendation / extended feature routes**
   - The backend includes additional routes not emphasized in the README structure: `assistant.js`, `vetAssistant.js`, `notifications.js`, and `products.js`.
   - Their presence suggests optional or newer subsystems for AI assistance, reminders, and product recommendations.
   - The README also mentions OpenRouter and email reminders, which aligns with `backend/services/emailService.js` and assistant-style endpoints.

11. **Frontend application shell**
   - `frontend/src/App.jsx` and `main.jsx` define the app shell, route tree, and provider composition.
   - Global UI state is split across `AuthContext`, `ThemeContext`, and `ToastContext`.
   - Layout components such as `Layout.jsx`, `Navbar.jsx`, `Sidebar.jsx`, and `BottomNav.jsx` handle responsive navigation patterns for desktop and mobile.

12. **Frontend data access pattern**
   - The frontend uses a layered client structure:
     - `services/api.js` for HTTP transport and auth headers/interceptors
     - feature hooks like `useCats.js`, `useTasks.js`, and `useVetRecords.js` for page-level data access
     - pages/components for presentation
   - This keeps server communication out of most UI components and makes the page layer mostly orchestration.

13. **Theming and presentation system**
   - Theme switching is a first-class architectural concern, not just a styling detail.
   - `ThemeContext.jsx` plus `ThemeSwitcher.jsx` drive the six-theme system, while Tailwind and CSS variables provide the visual implementation.
   - The landing page adds a separate presentation-heavy subsystem with Three.js in `LandingPage.jsx`.

14. **External services and deployment**
   - The app depends on **MongoDB Atlas** for persistence, **Vercel** for frontend hosting, **Render** for backend hosting, and likely email/API providers for reminders and AI features.
   - Runtime configuration is environment-driven, which matters for diagramming because frontend and backend are independently deployed and configured.

15. **What an architecture diagram should emphasize**
   - Show two main clients: browser SPA and API server.
   - Under the API, separate **auth**, **cats**, **tasks**, **vet records**, and the smaller assistant/notifications/product extensions.
   - Under the SPA, separate **routing/layout**, **global contexts**, **feature hooks/services**, and **page components**.
   - Draw MongoDB as the shared persistence layer behind the backend only, with JWT auth as the access boundary for protected endpoints.

Main entry points: [`frontend/src/App.jsx`](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/App.jsx) (App shell), [`backend/server.js`](https://github.com/salman-sensei/purrfect-care/blob/main/backend/server.js) (API server), [`frontend/src/hooks/useCats.js`](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/hooks/useCats.js) (Feature hooks), [`backend/routes/assistant.js`](https://github.com/salman-sensei/purrfect-care/blob/main/backend/routes/assistant.js) (Extensions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_shell["App shell<br/>SPA shell<br/>[App.jsx]"]
  node_frontend_contexts(("Global state<br/>React contexts<br/>[AuthContext.jsx]"))
  node_frontend_layout["Navigation layout<br/>UI chrome<br/>[Layout.jsx]"]
  node_frontend_auth_ui["Auth gate<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_frontend_data_hooks["Feature hooks<br/>data hooks<br/>[useCats.js]"]
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
  node_frontend_auth_service["Auth service<br/>client auth<br/>[auth.js]"]
  node_frontend_dashboard["Dashboard<br/>summary page<br/>[DashboardPage.jsx]"]
  node_frontend_cats["Cats UI<br/>feature pages<br/>[CatsPage.jsx]"]
  node_frontend_tasks["Checklist UI<br/>feature pages<br/>[ChecklistPage.jsx]"]
  node_frontend_vets["Vet UI<br/>feature pages<br/>[VetRecordsPage.jsx]"]
  node_frontend_special["Assistant pages<br/>extra pages"]
  node_frontend_theme(("Theme system<br/>presentation<br/>[ThemeContext.jsx]"))
end

subgraph group_backend["Backend API"]
  node_backend_server["API server<br/>Express bootstrap<br/>[server.js]"]
  node_backend_db[("DB connector<br/>Mongo connection<br/>[db.js]")]
  node_backend_auth["Auth domain<br/>jwt auth<br/>[authController.js]"]
  node_backend_cats["Cat domain<br/>CRUD API<br/>[catController.js]"]
  node_backend_tasks["Task domain<br/>CRUD API<br/>[taskController.js]"]
  node_backend_vets["Vet domain<br/>CRUD API<br/>[vetController.js]"]
  node_backend_extensions["Extensions<br/>assistant & notifications<br/>[assistant.js]"]
end

subgraph group_infra["Data & Integrations"]
  node_db[("MongoDB<br/>persistent store")]
  node_email["Email service<br/>notification service<br/>[emailService.js]"]
end

node_frontend_shell -->|"compose"| node_frontend_contexts
node_frontend_shell -->|"render"| node_frontend_layout
node_frontend_shell -->|"route guard"| node_frontend_auth_ui
node_frontend_shell -->|"route"| node_frontend_dashboard
node_frontend_shell -->|"route"| node_frontend_cats
node_frontend_shell -->|"route"| node_frontend_tasks
node_frontend_shell -->|"route"| node_frontend_vets
node_frontend_shell -->|"route"| node_frontend_special
node_frontend_contexts -->|"provide"| node_frontend_theme
node_frontend_cats -->|"use"| node_frontend_data_hooks
node_frontend_tasks -->|"use"| node_frontend_data_hooks
node_frontend_vets -->|"use"| node_frontend_data_hooks
node_frontend_data_hooks -->|"call"| node_frontend_api
node_frontend_auth_ui -->|"use"| node_frontend_auth_service
node_frontend_auth_service -->|"call"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_server
node_backend_server -->|"connect"| node_backend_db
node_backend_server -->|"mount"| node_backend_auth
node_backend_server -->|"mount"| node_backend_cats
node_backend_server -->|"mount"| node_backend_tasks
node_backend_server -->|"mount"| node_backend_vets
node_backend_server -->|"mount"| node_backend_extensions
node_backend_auth -->|"persist"| node_db
node_backend_cats -->|"persist"| node_db
node_backend_tasks -->|"persist"| node_db
node_backend_vets -->|"persist"| node_db
node_backend_extensions -->|"send"| node_email
node_backend_extensions -->|"read/write"| node_db
node_frontend_dashboard -->|"aggregate"| node_frontend_data_hooks

click node_frontend_shell "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/App.jsx"
click node_frontend_contexts "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_layout "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/components/Layout.jsx"
click node_frontend_auth_ui "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_frontend_data_hooks "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/hooks/useCats.js"
click node_frontend_api "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/services/api.js"
click node_frontend_auth_service "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/services/auth.js"
click node_frontend_dashboard "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_frontend_cats "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/CatsPage.jsx"
click node_frontend_tasks "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/ChecklistPage.jsx"
click node_frontend_vets "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/VetRecordsPage.jsx"
click node_frontend_special "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/ProductRecommendationsPage.jsx"
click node_frontend_theme "https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/context/ThemeContext.jsx"
click node_backend_server "https://github.com/salman-sensei/purrfect-care/blob/main/backend/server.js"
click node_backend_db "https://github.com/salman-sensei/purrfect-care/blob/main/backend/config/db.js"
click node_backend_auth "https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/authController.js"
click node_backend_cats "https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/catController.js"
click node_backend_tasks "https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/taskController.js"
click node_backend_vets "https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/vetController.js"
click node_backend_extensions "https://github.com/salman-sensei/purrfect-care/blob/main/backend/routes/assistant.js"
click node_email "https://github.com/salman-sensei/purrfect-care/blob/main/backend/services/emailService.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_shell,node_frontend_contexts,node_frontend_layout,node_frontend_auth_ui,node_frontend_data_hooks,node_frontend_api,node_frontend_auth_service,node_frontend_dashboard,node_frontend_cats,node_frontend_tasks,node_frontend_vets,node_frontend_special,node_frontend_theme toneBlue
class node_backend_server,node_backend_db,node_backend_auth,node_backend_cats,node_backend_tasks,node_backend_vets,node_backend_extensions toneAmber
class node_db,node_email toneMint
```

## Components

### Frontend SPA

React/Vite client application with routed pages, shared state, and feature hooks.

- [App shell](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/App.jsx): SPA shell · Bootstraps routing, providers, and global layout composition. · `frontend/src/App.jsx`
- [Global state](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/context/AuthContext.jsx): React contexts · Auth, theme, and toast application state providers. · `frontend/src/context/AuthContext.jsx`
- [Navigation layout](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/components/Layout.jsx): UI chrome · Responsive shell for desktop and mobile navigation. · `frontend/src/components/Layout.jsx`
- [Auth gate](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/components/ProtectedRoute.jsx): route guard · Session handling, protected routes, and login/signup flows. · `frontend/src/components/ProtectedRoute.jsx`
- [Feature hooks](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/hooks/useCats.js): data hooks · Page-level data access for cats, tasks, and vet records. · `frontend/src/hooks/useCats.js`
- [API client](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/services/api.js): HTTP client · Shared transport layer for authenticated backend requests. · `frontend/src/services/api.js`
- [Auth service](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/services/auth.js): client auth · Client-side authentication helpers and token/session handling. · `frontend/src/services/auth.js`
- [Dashboard](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/DashboardPage.jsx): summary page · Cross-domain read-composition surface for cats, tasks, and vet reminders. · `frontend/src/pages/DashboardPage.jsx`
- [Cats UI](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/CatsPage.jsx): feature pages · Cat listing, profile, and editing experience. · `frontend/src/pages/CatsPage.jsx`
- [Checklist UI](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/ChecklistPage.jsx): feature pages · Daily tasks and completion tracking interface. · `frontend/src/pages/ChecklistPage.jsx`
- [Vet UI](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/VetRecordsPage.jsx): feature pages · Vet record management and upcoming visit views. · `frontend/src/pages/VetRecordsPage.jsx`
- [Assistant pages](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/pages/ProductRecommendationsPage.jsx): extra pages · Extended experiences for recommendations, symptom help, and shared cat views. · `frontend/src/pages/ProductRecommendationsPage.jsx`
- [Theme system](https://github.com/salman-sensei/purrfect-care/blob/main/frontend/src/context/ThemeContext.jsx): presentation · Theme switching and visual styling composition. · `frontend/src/context/ThemeContext.jsx`

### Backend API

Express application exposing auth, CRUD, and assistant-oriented endpoints.

- [API server](https://github.com/salman-sensei/purrfect-care/blob/main/backend/server.js): Express bootstrap · Express app setup, middleware, route mounting, and startup wiring. · `backend/server.js`
- [DB connector](https://github.com/salman-sensei/purrfect-care/blob/main/backend/config/db.js): Mongo connection · MongoDB Atlas connection setup and environment-driven configuration. · `backend/config/db.js`
- [Auth domain](https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/authController.js): jwt auth · User model, login/register controller, and route protection middleware. · `backend/controllers/authController.js`
- [Cat domain](https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/catController.js): CRUD API · Cat model, controller, and routes for owned cat records. · `backend/controllers/catController.js`
- [Task domain](https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/taskController.js): CRUD API · Task model, controller, and routes for daily checklist management. · `backend/controllers/taskController.js`
- [Vet domain](https://github.com/salman-sensei/purrfect-care/blob/main/backend/controllers/vetController.js): CRUD API · Vet record model, controller, and routes for appointment tracking. · `backend/controllers/vetController.js`
- [Extensions](https://github.com/salman-sensei/purrfect-care/blob/main/backend/routes/assistant.js): assistant & notifications · Assistant, notifications, products, and email-oriented backend features. · `backend/routes/assistant.js`

### Data & Integrations

Persistence and external services used by the application.

- **MongoDB**: persistent store · Shared persistence layer for user-owned cats, tasks, vet records, and accounts.
- [Email service](https://github.com/salman-sensei/purrfect-care/blob/main/backend/services/emailService.js): notification service · Outbound reminder delivery and notification support. · `backend/services/emailService.js`

## Connections

- App shell → Global state: compose · App wraps the UI with auth, theme, and toast providers.
- App shell → Navigation layout: render · App shell renders the responsive navigation/layout frame.
- App shell → Auth gate: route guard · Protected routes gate authenticated pages.
- App shell → Dashboard: route · Dashboard is one of the primary routed pages.
- App shell → Cats UI: route · Cats pages are mounted from the application router.
- App shell → Checklist UI: route · Checklist pages are mounted from the application router.
- App shell → Vet UI: route · Vet records pages are mounted from the application router.
- App shell → Assistant pages: route · Auxiliary assistant and recommendation pages are routed here.
- Global state → Theme system: provide · Theme context powers switching and visual state.
- Cats UI → Feature hooks: use · Cat pages rely on feature hooks for fetching and mutations.
- Checklist UI → Feature hooks: use · Task pages rely on feature hooks for fetching and mutations.
- Vet UI → Feature hooks: use · Vet pages rely on feature hooks for fetching and mutations.
- Feature hooks → API client: call · Feature hooks delegate transport to the shared API client.
- Auth gate → Auth service: use · Auth gating and session flow depend on client auth helpers.
- Auth service → API client: call · Login/session operations use the shared HTTP client.
- API client → API server: HTTP · SPA communicates with the backend over authenticated API calls.
- API server → DB connector: connect · Server initializes the MongoDB connection during bootstrap.
- API server → Auth domain: mount · Auth routes and middleware are attached in the Express app.
- API server → Cat domain: mount · Cat CRUD endpoints are mounted under the API server.
- API server → Task domain: mount · Task CRUD endpoints are mounted under the API server.
- API server → Vet domain: mount · Vet record endpoints are mounted under the API server.
- API server → Extensions: mount · Assistant, notifications, and product routes extend the API surface.
- Auth domain → MongoDB: persist · User accounts are stored in MongoDB via Mongoose.
- Cat domain → MongoDB: persist · Cat entities are stored in MongoDB via Mongoose.
- Task domain → MongoDB: persist · Task entities are stored in MongoDB via Mongoose.
- Vet domain → MongoDB: persist · Vet records are stored in MongoDB via Mongoose.
- Extensions → Email service: send · Reminder-oriented features can emit email notifications.
- Extensions → MongoDB: read/write · Extended features may also read or persist application data.
- Dashboard → Feature hooks: aggregate · Dashboard composes summaries from multiple feature data sources.
