How salman-sensei/purrfect-care works
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: App.jsx App shell · server.js API server · useCats.js Feature hooks · assistant.js Extensions
Components 22
Frontend SPA
React/Vite client application with routed pages, shared state, and feature hooks.
- App shell · Bootstraps routing, providers, and global layout composition.
frontend/src/App.jsx - Global state · Auth, theme, and toast application state providers.
frontend/src/context/AuthContext.jsx - Navigation layout · Responsive shell for desktop and mobile navigation.
frontend/src/components/Layout.jsx - Auth gate · Session handling, protected routes, and login/signup flows.
frontend/src/components/ProtectedRoute.jsx - Feature hooks · Page-level data access for cats, tasks, and vet records.
frontend/src/hooks/useCats.js - API client · Shared transport layer for authenticated backend requests.
frontend/src/services/api.js - Auth service · Client-side authentication helpers and token/session handling.
frontend/src/services/auth.js - Dashboard · Cross-domain read-composition surface for cats, tasks, and vet reminders.
frontend/src/pages/DashboardPage.jsx - Cats UI · Cat listing, profile, and editing experience.
frontend/src/pages/CatsPage.jsx - Checklist UI · Daily tasks and completion tracking interface.
frontend/src/pages/ChecklistPage.jsx - Vet UI · Vet record management and upcoming visit views.
frontend/src/pages/VetRecordsPage.jsx - Assistant pages · Extended experiences for recommendations, symptom help, and shared cat views.
frontend/src/pages/ProductRecommendationsPage.jsx - Theme system · Theme switching and visual styling composition.
frontend/src/context/ThemeContext.jsx
Backend API
Express application exposing auth, CRUD, and assistant-oriented endpoints.
- API server · Express app setup, middleware, route mounting, and startup wiring.
backend/server.js - DB connector · MongoDB Atlas connection setup and environment-driven configuration.
backend/config/db.js - Auth domain · User model, login/register controller, and route protection middleware.
backend/controllers/authController.js - Cat domain · Cat model, controller, and routes for owned cat records.
backend/controllers/catController.js - Task domain · Task model, controller, and routes for daily checklist management.
backend/controllers/taskController.js - Vet domain · Vet record model, controller, and routes for appointment tracking.
backend/controllers/vetController.js - Extensions · Assistant, notifications, products, and email-oriented backend features.
backend/routes/assistant.js
Data & Integrations
Persistence and external services used by the application.
- MongoDB · Shared persistence layer for user-owned cats, tasks, vet records, and accounts.
- Email service · Outbound reminder delivery and notification support.
backend/services/emailService.js
Connections 29
- 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.