# ashishb20/recallops architecture

> Architecture diagram of the GitHub repository ashishb20/recallops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashishb20/recallops
- Repository: https://github.com/ashishb20/recallops

## Overview

1. **Overall shape**
   - RecallOps is a two-tier full-stack app: a **React/Vite frontend** in `client/` and a **Node/Express API** in `server/`.
   - The architecture is centered on a single domain: **learning tasks managed with 1-4-7 spaced repetition scheduling**.

2. **Frontend presentation layer**
   - The UI lives in `client/src/` and is organized by **pages** (`Dashboard`, `Login`, `Register`, `NotFound`) and reusable **components** (`TaskCard`, `TaskDropdown`, `AddTaskModal`, `EditTaskModal`, `Stats`, `Timer`, `Navbar`, `Footer`, `ToastContainer`, `ErrorBoundary`).
   - `Dashboard` is the main workspace where users view, create, edit, and review tasks.
   - `Login` and `Register` form the public entry path, while `NotFound` handles unknown routes.

3. **Client state and auth boundary**
   - `AuthContext` plus the `useAuth` hook provide app-wide authentication state.
   - This is the client-side boundary that decides whether a user sees the learning dashboard or the auth screens.
   - The presence of `ErrorBoundary` and toast components suggests the UI is designed to handle runtime failures and async feedback gracefully.

4. **Client service layer**
   - `client/src/services/api.js` is the HTTP access layer used by the rest of the frontend.
   - `authService.js` and `taskService.js` isolate API calls from UI code, which keeps pages/components focused on rendering and interaction.
   - This creates a clean separation: **components manage user interaction**, while **services manage server communication**.

5. **Backend API layer**
   - The server is an Express app with route modules in `server/routes/` and business logic in `server/controllers/`.
   - Auth and task operations are split into separate endpoints, reflecting two main backend concerns: **identity** and **learning-task lifecycle**.
   - `server/server.js` is the API entry point and likely wires middleware, routes, and database startup.

6. **Authentication flow**
   - `authController.js`, `authRoutes.js`/`auth.js`, and `middleware/auth.js` indicate token-protected API access.
   - The likely flow is: user registers/logs in on the frontend → backend validates credentials → client stores auth state → subsequent task requests include auth credentials and pass through middleware.
   - This boundary separates public auth endpoints from protected task management endpoints.

7. **Task and spaced-repetition domain**
   - `Task.js` is the core domain model and represents the learning item being reviewed.
   - `taskController.js` handles task CRUD and review progression.
   - `utils/dateHelper.js` is important because it likely computes review timing based on the **1 day / 4 days / 7 days** schedule described in the README.
   - That means the backend owns the authoritative scheduling logic, not the client.

8. **Persistence layer**
   - `config/db.js` connects the application to its database, and the `User` and `Task` models indicate a MongoDB/Mongoose-style persistence layer.
   - Users and tasks are stored separately, with tasks likely linked to the authenticated user.
   - This creates a clear data boundary: the frontend never talks to the database directly; all persistence goes through controllers and models.

9. **User-facing task workflow**
   - The main loop is: **create task → review task when due → update its repetition stage/date → display updated stats**.
   - `AddTaskModal` and `EditTaskModal` handle task authoring; `TaskCard` and `TaskDropdown` support browsing and action menus; `Timer` suggests time-based review or focus behavior; `Stats` summarizes progress.
   - This workflow is what turns the app from a generic task manager into a spaced-repetition learning tool.

10. **Routing and navigation**
   - On the client, page-level routing likely switches between dashboard and auth views.
   - On the server, route modules map HTTP paths to controller actions for auth and tasks.
   - The architecture is therefore split into **UI routing** on the frontend and **REST-style API routing** on the backend.

11. **Styling and runtime stack**
   - The frontend uses **Vite**, **React**, **Tailwind/PostCSS**, and ESLint tooling.
   - `vercel.json` suggests the client is prepared for Vercel deployment.
   - The backend is a standard Node.js service with package management isolated from the client, which implies separate build/deploy concerns for frontend and API.

12. **Diagramming guidance**
   - A good architecture diagram should show three main layers: **React UI**, **Express API**, and **database/persistence**.
   - Within the API, highlight two domains: **authentication** and **task scheduling/review logic**.
   - The most important data flow is the review schedule update: frontend action → task API → controller/model/date helper → persisted task with next due date → refreshed dashboard/UI state.

Main entry points: [`client/src/App.jsx`](https://github.com/ashishb20/recallops/blob/main/client/src/App.jsx) (App shell), [`client/src/pages/Dashboard.jsx`](https://github.com/ashishb20/recallops/blob/main/client/src/pages/Dashboard.jsx) (Dashboard), [`client/src/context/AuthContext.jsx`](https://github.com/ashishb20/recallops/blob/main/client/src/context/AuthContext.jsx) (Auth state), [`server/controllers/taskController.js`](https://github.com/ashishb20/recallops/blob/main/server/controllers/taskController.js) (Task controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["App shell<br/>react entry<br/>[App.jsx]"]
  node_client_auth(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_client_dashboard["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_client_login["Login<br/>page<br/>[Login.jsx]"]
  node_client_register["Register<br/>page<br/>[Register.jsx]"]
  node_client_notfound["Not Found<br/>page<br/>[NotFound.jsx]"]
  node_client_task_ui["Task UI<br/>components<br/>[TaskCard.jsx]"]
  node_client_feedback["Feedback UI<br/>components<br/>[ToastContainer.jsx]"]
  node_client_services["API services<br/>service layer<br/>[api.js]"]
  node_client_authsvc["Auth service<br/>[authService.js]"]
  node_client_tasksvc["Task service<br/>[taskService.js]"]
end

subgraph group_server["Server"]
  node_server_entry["API server<br/>express entry<br/>[server.js]"]
  node_server_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_server_task_routes["Task routes<br/>[tasks.js]"]
  node_server_auth_ctrl["Auth controller<br/>[authController.js]"]
  node_server_task_ctrl["Task controller<br/>[taskController.js]"]
  node_server_auth_mid["Auth middleware<br/>[auth.js]"]
  node_server_date["Date helper<br/>scheduler<br/>[dateHelper.js]"]
end

subgraph group_data["Data"]
  node_db_config[("DB config<br/>database connection<br/>[db.js]")]
  node_model_user[("User model<br/>[User.js]")]
  node_model_task[("Task model<br/>[Task.js]")]
end

node_client_app -->|"provides auth"| node_client_auth
node_client_app -->|"routes to"| node_client_dashboard
node_client_app -->|"routes to"| node_client_login
node_client_app -->|"routes to"| node_client_register
node_client_app -->|"fallback"| node_client_notfound
node_client_dashboard -->|"uses"| node_client_task_ui
node_client_dashboard -->|"uses"| node_client_feedback
node_client_login -->|"calls"| node_client_authsvc
node_client_register -->|"calls"| node_client_authsvc
node_client_dashboard -->|"calls"| node_client_tasksvc
node_client_services -->|"wraps"| node_client_authsvc
node_client_services -->|"wraps"| node_client_tasksvc
node_client_authsvc -->|"HTTP auth"| node_server_auth_routes
node_client_tasksvc -->|"HTTP tasks"| node_server_task_routes
node_server_entry -->|"mounts"| node_server_auth_routes
node_server_entry -->|"mounts"| node_server_task_routes
node_server_auth_routes -->|"delegates"| node_server_auth_ctrl
node_server_task_routes -->|"protects"| node_server_auth_mid
node_server_task_routes -->|"delegates"| node_server_task_ctrl
node_server_auth_ctrl -->|"reads/writes"| node_model_user
node_server_task_ctrl -->|"reads/writes"| node_model_task
node_server_task_ctrl -->|"computes due date"| node_server_date
node_server_auth_ctrl -->|"uses db"| node_db_config
node_server_task_ctrl -->|"uses db"| node_db_config
node_model_user -->|"stored via"| node_db_config
node_model_task -->|"stored via"| node_db_config
node_client_auth -.->|"gates access"| node_client_dashboard
node_client_auth -.->|"gates access"| node_client_login
node_client_auth -.->|"gates access"| node_client_register
node_server_auth_mid -->|"verifies token"| node_server_auth_ctrl

click node_client_app "https://github.com/ashishb20/recallops/blob/main/client/src/App.jsx"
click node_client_auth "https://github.com/ashishb20/recallops/blob/main/client/src/context/AuthContext.jsx"
click node_client_dashboard "https://github.com/ashishb20/recallops/blob/main/client/src/pages/Dashboard.jsx"
click node_client_login "https://github.com/ashishb20/recallops/blob/main/client/src/pages/Login.jsx"
click node_client_register "https://github.com/ashishb20/recallops/blob/main/client/src/pages/Register.jsx"
click node_client_notfound "https://github.com/ashishb20/recallops/blob/main/client/src/pages/NotFound.jsx"
click node_client_task_ui "https://github.com/ashishb20/recallops/blob/main/client/src/components/TaskCard.jsx"
click node_client_feedback "https://github.com/ashishb20/recallops/blob/main/client/src/components/ToastContainer.jsx"
click node_client_services "https://github.com/ashishb20/recallops/blob/main/client/src/services/api.js"
click node_client_authsvc "https://github.com/ashishb20/recallops/blob/main/client/src/services/authService.js"
click node_client_tasksvc "https://github.com/ashishb20/recallops/blob/main/client/src/services/taskService.js"
click node_server_entry "https://github.com/ashishb20/recallops/blob/main/server/server.js"
click node_server_auth_routes "https://github.com/ashishb20/recallops/blob/main/server/routes/authRoutes.js"
click node_server_task_routes "https://github.com/ashishb20/recallops/blob/main/server/routes/tasks.js"
click node_server_auth_ctrl "https://github.com/ashishb20/recallops/blob/main/server/controllers/authController.js"
click node_server_task_ctrl "https://github.com/ashishb20/recallops/blob/main/server/controllers/taskController.js"
click node_server_auth_mid "https://github.com/ashishb20/recallops/blob/main/server/middleware/auth.js"
click node_server_date "https://github.com/ashishb20/recallops/blob/main/server/utils/dateHelper.js"
click node_db_config "https://github.com/ashishb20/recallops/blob/main/server/config/db.js"
click node_model_user "https://github.com/ashishb20/recallops/blob/main/server/models/User.js"
click node_model_task "https://github.com/ashishb20/recallops/blob/main/server/models/Task.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_client_app,node_client_auth,node_client_dashboard,node_client_login,node_client_register,node_client_notfound,node_client_task_ui,node_client_feedback,node_client_services,node_client_authsvc,node_client_tasksvc toneBlue
class node_server_entry,node_server_auth_routes,node_server_task_routes,node_server_auth_ctrl,node_server_task_ctrl,node_server_auth_mid,node_server_date toneAmber
class node_db_config,node_model_user,node_model_task toneMint
```

## Components

### Client

React/Vite frontend and UI state

- [App shell](https://github.com/ashishb20/recallops/blob/main/client/src/App.jsx): react entry · Top-level client composition and routing · `client/src/App.jsx`
- [Auth state](https://github.com/ashishb20/recallops/blob/main/client/src/context/AuthContext.jsx): context · Global authentication boundary for the UI · `client/src/context/AuthContext.jsx`
- [Dashboard](https://github.com/ashishb20/recallops/blob/main/client/src/pages/Dashboard.jsx): page · Main workspace for creating, reviewing, and editing tasks · `client/src/pages/Dashboard.jsx`
- [Login](https://github.com/ashishb20/recallops/blob/main/client/src/pages/Login.jsx): page · Public sign-in screen · `client/src/pages/Login.jsx`
- [Register](https://github.com/ashishb20/recallops/blob/main/client/src/pages/Register.jsx): page · Public account creation screen · `client/src/pages/Register.jsx`
- [Not Found](https://github.com/ashishb20/recallops/blob/main/client/src/pages/NotFound.jsx): page · Fallback route for unknown paths · `client/src/pages/NotFound.jsx`
- [Task UI](https://github.com/ashishb20/recallops/blob/main/client/src/components/TaskCard.jsx): components · Task cards, menus, and modal editing surfaces · `client/src/components/TaskCard.jsx`
- [Feedback UI](https://github.com/ashishb20/recallops/blob/main/client/src/components/ToastContainer.jsx): components · Toast, error boundary, stats, and timer presentation · `client/src/components/ToastContainer.jsx`
- [API services](https://github.com/ashishb20/recallops/blob/main/client/src/services/api.js): service layer · HTTP access layer used by the frontend · `client/src/services/api.js`
- [Auth service](https://github.com/ashishb20/recallops/blob/main/client/src/services/authService.js): service · Client auth API wrapper · `client/src/services/authService.js`
- [Task service](https://github.com/ashishb20/recallops/blob/main/client/src/services/taskService.js): service · Client task API wrapper · `client/src/services/taskService.js`

### Server

Express API and domain logic

- [API server](https://github.com/ashishb20/recallops/blob/main/server/server.js): express entry · Express bootstrap and middleware wiring · `server/server.js`
- [Auth routes](https://github.com/ashishb20/recallops/blob/main/server/routes/authRoutes.js): route · Authentication endpoints · `server/routes/authRoutes.js`
- [Task routes](https://github.com/ashishb20/recallops/blob/main/server/routes/tasks.js): route · Task and review endpoints · `server/routes/tasks.js`
- [Auth controller](https://github.com/ashishb20/recallops/blob/main/server/controllers/authController.js): controller · Credential validation and user session handling · `server/controllers/authController.js`
- [Task controller](https://github.com/ashishb20/recallops/blob/main/server/controllers/taskController.js): controller · Task CRUD and review progression · `server/controllers/taskController.js`
- [Auth middleware](https://github.com/ashishb20/recallops/blob/main/server/middleware/auth.js): middleware · Protects authenticated API access · `server/middleware/auth.js`
- [Date helper](https://github.com/ashishb20/recallops/blob/main/server/utils/dateHelper.js): scheduler · Spaced-repetition timing logic · `server/utils/dateHelper.js`

### Data

Database connection and persisted models

- [DB config](https://github.com/ashishb20/recallops/blob/main/server/config/db.js): database connection · Database connection bootstrap · `server/config/db.js`
- [User model](https://github.com/ashishb20/recallops/blob/main/server/models/User.js): model · Persisted user identity record · `server/models/User.js`
- [Task model](https://github.com/ashishb20/recallops/blob/main/server/models/Task.js): model · Persisted learning task and review state · `server/models/Task.js`

## Connections

- App shell → Auth state: provides auth · App wraps the UI in authentication state
- App shell → Dashboard: routes to · Authenticated workspace view
- App shell → Login: routes to · Public sign-in view
- App shell → Register: routes to · Public registration view
- App shell → Not Found: fallback · Unknown route handling
- Dashboard → Task UI: uses · Dashboard renders task interactions
- Dashboard → Feedback UI: uses · Dashboard surfaces stats, toasts, and timers
- Login → Auth service: calls · Login submits credentials through auth service
- Register → Auth service: calls · Registration submits credentials through auth service
- Dashboard → Task service: calls · Dashboard loads and mutates tasks through task service
- API services → Auth service: wraps · Shared HTTP layer under auth calls
- API services → Task service: wraps · Shared HTTP layer under task calls
- Auth service → Auth routes: HTTP auth · Client authentication requests hit auth endpoints
- Task service → Task routes: HTTP tasks · Client task requests hit task endpoints
- API server → Auth routes: mounts · Express mounts auth routes
- API server → Task routes: mounts · Express mounts task routes
- Auth routes → Auth controller: delegates · Auth routes pass work to the controller
- Task routes → Auth middleware: protects · Task access is authenticated
- Task routes → Task controller: delegates · Task routes pass work to the controller
- Auth controller → User model: reads/writes · User records are created and verified
- Task controller → Task model: reads/writes · Task records are created and updated
- Task controller → Date helper: computes due date · Review progression uses spaced-repetition timing
- Auth controller → DB config: uses db · Controllers operate through the database connection
- Task controller → DB config: uses db · Task persistence uses the database connection
- User model → DB config: stored via · User model persists through the shared DB connection
- Task model → DB config: stored via · Task model persists through the shared DB connection
- Auth state → Dashboard: gates access · Authenticated users reach the dashboard
- Auth state → Login: gates access · Unauthenticated users reach login
- Auth state → Register: gates access · Unauthenticated users can register
- Auth middleware → Auth controller: verifies token · Protected routes rely on auth verification