# riteshpanchal279/ai-task-manager architecture

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

- Interactive diagram: https://gitdiagram.com/riteshpanchal279/ai-task-manager
- Repository: https://github.com/riteshpanchal279/ai-task-manager

## Overview

1. **Overall shape**
   - This is a two-app repository: a **Next.js frontend** in `frontend/` and a **Node.js backend API** in `backend/`.
   - They are loosely coupled through HTTP calls; the frontend owns the user experience, while the backend owns persistence, business rules, and AI/task generation.

2. **Frontend boundary**
   - The frontend uses the **Next.js App Router** (`src/app/`) with a single page entry and global layout/styles.
   - UI is built from reusable components under `src/components/`, with ShadCN-style primitives in `src/components/ui/`.
   - The app is structured as a client-heavy dashboard rather than server-rendered business logic.

3. **Frontend feature composition**
   - `TaskDashboard` appears to be the main orchestration component for the task workspace.
   - Supporting pieces split the UI by responsibility: task list/item rendering, task creation/edit dialogs/forms, stats cards, and an AI task generator panel.
   - `AuthGuard` provides route/session gating on the client side.

4. **Frontend state and API access**
   - `src/hooks/useTasks.ts` is the main state/data hook for task lifecycle management.
   - This hook likely centralizes fetching, optimistic updates, and mutation flows for tasks.
   - `frontend/types/task.ts` defines the task model used by UI components, keeping component props and API data aligned.

5. **Backend boundary**
   - The backend is a standalone API app in `backend/src/` with explicit layers: **routes → services → database**.
   - `src/index.ts` is the entrypoint that wires the server together.
   - `src/utils/response.ts` suggests a shared response/envelope format used across endpoints.

6. **HTTP API structure**
   - Routes are split by domain: `users`, `tasks`, and `stats`.
   - `tasks.ts` is likely the core CRUD surface for task creation, updates, completion toggles, and deletion.
   - `users.ts` handles user-related reads or identity mapping, while `stats.ts` aggregates task metrics for dashboard cards.

7. **Business logic layer**
   - The service layer contains the main application logic:
     - `taskService.ts` for task rules and persistence workflows,
     - `userService.ts` for user resolution/management,
     - `aiService.ts` for Gemini-backed task generation.
   - This separation keeps route handlers thin and makes the backend easier to diagram as a three-tier service.

8. **Database layer**
   - `src/config/database.ts` and `src/db/schema.ts` show a **Drizzle ORM + PostgreSQL** setup.
   - The schema file defines the authoritative tables/entities used by the services.
   - `drizzle.config.ts` indicates migrations/schema tooling is part of the backend boundary.

9. **Auth and request protection**
   - `src/middleware/auth.ts` is the backend guard layer, likely validating a session/user identity before task operations.
   - The README mentions Clerk or Firebase Auth, so identity is external to the backend and then enforced server-side through middleware.
   - This means user-specific task isolation is a cross-cutting concern, not just a frontend concern.

10. **AI integration path**
   - `aiService.ts` is the integration point to **Google Gemini API**.
   - The frontend likely triggers AI generation from `AITaskGenerator`, sends input to the backend, and the backend returns generated task suggestions.
   - AI is therefore an external dependency behind a backend service boundary, not directly embedded in the UI.

11. **Stats/data aggregation**
   - `stats.ts` plus `StatsCards` imply a dedicated read model for dashboard metrics such as total tasks, completed tasks, and progress.
   - This is a separate API concern from task CRUD, which helps keep list operations and summary computations distinct.

12. **Technology/runtime split**
   - Frontend: **Next.js + TypeScript + Tailwind CSS** with component composition and local hooks for state.
   - Backend: **Node.js + TypeScript + Drizzle + PostgreSQL** with service-based business logic.
   - The repo is organized as a classic client/API/database architecture, with external auth and AI services feeding into the backend.

13. **What to draw in an architecture diagram**
   - Show the frontend as a dashboard UI that calls the backend API for tasks, stats, and AI suggestions.
   - Show middleware-protected backend routes delegating into services.
   - Show services writing to PostgreSQL through Drizzle, and separately calling Gemini for AI generation.
   - Show external auth as a trust input into the backend rather than as the system of record for tasks.

Main entry points: [`frontend/src/components/TaskDashboard.tsx`](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskDashboard.tsx) (Task Dashboard), [`backend/src/services`](https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/services) (Services), [`backend/src/routes`](https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/routes) (API Routes), [`frontend/types/task.ts`](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/types/task.ts) (Task Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>next app"]
  node_frontend_dashboard["Task Dashboard<br/>workspace UI<br/>[TaskDashboard.tsx]"]
  node_frontend_auth["Auth Guard<br/>client guard<br/>[AuthGuard.tsx]"]
  node_frontend_tasks_hook["useTasks<br/>state hook<br/>[useTasks.ts]"]
  node_frontend_task_list["Task List<br/>task rendering<br/>[TaskList.tsx]"]
  node_frontend_task_form["Task Form<br/>task input<br/>[TaskForm.tsx]"]
  node_frontend_task_dialog["Edit Dialog<br/>ui dialog<br/>[TaskEditDialog.tsx]"]
  node_frontend_stats["Stats Cards<br/>summary UI<br/>[StatsCards.tsx]"]
  node_frontend_ai_panel["AI Generator<br/>ai panel"]
  node_frontend_ui["UI Primitives<br/>component kit"]
  node_frontend_task_type["Task Types<br/>shared model<br/>[task.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Server Entry<br/>api bootstrap<br/>[index.ts]"]
  node_backend_routes["API Routes<br/>http routes"]
  node_backend_services["Services<br/>business logic"]
  node_backend_auth["Auth Middleware<br/>request guard<br/>[auth.ts]"]
  node_backend_db[("Database Layer<br/>orm/db")]
  node_backend_response["Response Utils<br/>api envelope<br/>[response.ts]"]
end

subgraph group_external["External"]
  node_external_postgres[("PostgreSQL<br/>database")]
  node_external_gemini{{"Gemini API<br/>ai service"}}
  node_external_auth{{"Auth Provider<br/>identity provider"}}
end

node_frontend_app -->|"renders"| node_frontend_dashboard
node_frontend_dashboard -->|"protected by"| node_frontend_auth
node_frontend_dashboard -->|"uses"| node_frontend_tasks_hook
node_frontend_dashboard -->|"composes"| node_frontend_task_list
node_frontend_dashboard -->|"composes"| node_frontend_task_form
node_frontend_dashboard -->|"composes"| node_frontend_task_dialog
node_frontend_dashboard -->|"composes"| node_frontend_stats
node_frontend_dashboard -->|"composes"| node_frontend_ai_panel
node_frontend_task_list -->|"types"| node_frontend_task_type
node_frontend_task_form -->|"types"| node_frontend_task_type
node_frontend_tasks_hook -->|"uses"| node_frontend_task_type
node_frontend_dashboard -->|"calls"| node_backend_routes
node_frontend_ai_panel -->|"calls"| node_backend_services
node_backend_entry -->|"wires"| node_backend_routes
node_backend_entry -->|"installs"| node_backend_auth
node_backend_routes -->|"delegates"| node_backend_services
node_backend_services -->|"reads/writes"| node_backend_db
node_backend_services -->|"calls"| node_external_gemini
node_backend_auth -->|"verifies"| node_external_auth
node_backend_db -->|"stores in"| node_external_postgres
node_backend_routes -->|"formats"| node_backend_response
node_backend_services -->|"returns"| node_backend_response

click node_frontend_app "https://github.com/riteshpanchal279/ai-task-manager/tree/main/frontend/src/app"
click node_frontend_dashboard "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskDashboard.tsx"
click node_frontend_auth "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/AuthGuard.tsx"
click node_frontend_tasks_hook "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/hooks/useTasks.ts"
click node_frontend_task_list "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskList.tsx"
click node_frontend_task_form "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskForm.tsx"
click node_frontend_task_dialog "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskEditDialog.tsx"
click node_frontend_stats "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/StatsCards.tsx"
click node_frontend_ai_panel "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/AITaskGenerator.tsx"
click node_frontend_ui "https://github.com/riteshpanchal279/ai-task-manager/tree/main/frontend/src/components/ui"
click node_frontend_task_type "https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/types/task.ts"
click node_backend_entry "https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/index.ts"
click node_backend_routes "https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/routes"
click node_backend_services "https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/services"
click node_backend_auth "https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/middleware/auth.ts"
click node_backend_db "https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/db"
click node_backend_response "https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/utils/response.ts"

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_app,node_frontend_dashboard,node_frontend_auth,node_frontend_tasks_hook,node_frontend_task_list,node_frontend_task_form,node_frontend_task_dialog,node_frontend_stats,node_frontend_ai_panel,node_frontend_ui,node_frontend_task_type toneBlue
class node_backend_entry,node_backend_routes,node_backend_services,node_backend_auth,node_backend_db,node_backend_response toneAmber
class node_external_postgres,node_external_gemini,node_external_auth toneMint
```

## Components

### Frontend

Next.js client app and dashboard UI

- [App Router](https://github.com/riteshpanchal279/ai-task-manager/tree/main/frontend/src/app): next app · Next.js app entry, layout, and page shell · `frontend/src/app`
- [Task Dashboard](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskDashboard.tsx): workspace UI · Main task workspace and orchestration component · `frontend/src/components/TaskDashboard.tsx`
- [Auth Guard](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/AuthGuard.tsx): client guard · Client-side route and session gating · `frontend/src/components/AuthGuard.tsx`
- [useTasks](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/hooks/useTasks.ts): state hook · Task fetching and mutation state management · `frontend/src/hooks/useTasks.ts`
- [Task List](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskList.tsx): task rendering · Task list and item presentation · `frontend/src/components/TaskList.tsx`
- [Task Form](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskForm.tsx): task input · Create and edit task form flows · `frontend/src/components/TaskForm.tsx`
- [Edit Dialog](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/TaskEditDialog.tsx): ui dialog · Task editing dialog wrapper · `frontend/src/components/TaskEditDialog.tsx`
- [Stats Cards](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/StatsCards.tsx): summary UI · Dashboard metrics and progress cards · `frontend/src/components/StatsCards.tsx`
- [AI Generator](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/src/components/AITaskGenerator.tsx): ai panel · Task generation UI for suggested tasks · `frontend/src/components/AITaskGenerator.tsx`
- [UI Primitives](https://github.com/riteshpanchal279/ai-task-manager/tree/main/frontend/src/components/ui): component kit · Shared shadcn-style UI building blocks · `frontend/src/components/ui`
- [Task Types](https://github.com/riteshpanchal279/ai-task-manager/blob/main/frontend/types/task.ts): shared model · Frontend task data shape shared across components · `frontend/types/task.ts`

### Backend

Node.js API with routes, services, and database access

- [Server Entry](https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/index.ts): api bootstrap · Backend server startup and wiring · `backend/src/index.ts`
- [API Routes](https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/routes): http routes · Domain route handlers for tasks, users, and stats · `backend/src/routes`
- [Services](https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/services): business logic · Application logic for tasks, users, and AI generation · `backend/src/services`
- [Auth Middleware](https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/middleware/auth.ts): request guard · Server-side identity and access protection · `backend/src/middleware/auth.ts`
- [Database Layer](https://github.com/riteshpanchal279/ai-task-manager/tree/main/backend/src/db): orm/db · Drizzle configuration and PostgreSQL schema access · `backend/src/db`
- [Response Utils](https://github.com/riteshpanchal279/ai-task-manager/blob/main/backend/src/utils/response.ts): api envelope · Shared response formatting helpers · `backend/src/utils/response.ts`

### External

Outside services consumed by the backend

- **PostgreSQL**: database · Persistent task and user data store
- **Gemini API**: ai service · External model API used for task generation
- **Auth Provider**: identity provider · External authentication source such as Clerk or Firebase

## Connections

- App Router → Task Dashboard: renders · App shell mounts the main dashboard
- Task Dashboard → Auth Guard: protected by · Dashboard access is gated on the client
- Task Dashboard → useTasks: uses · Dashboard reads and mutates task state through the hook
- Task Dashboard → Task List: composes · Dashboard includes task list rendering
- Task Dashboard → Task Form: composes · Dashboard includes task creation/edit flows
- Task Dashboard → Edit Dialog: composes · Dashboard opens task edit dialogs
- Task Dashboard → Stats Cards: composes · Dashboard shows summary metrics
- Task Dashboard → AI Generator: composes · Dashboard exposes AI task generation
- Task List → Task Types: types · Task list consumes the shared task model
- Task Form → Task Types: types · Forms are aligned to the task model
- useTasks → Task Types: uses · Hook centralizes task data shape
- Task Dashboard → API Routes: calls · Frontend invokes backend APIs for tasks and stats
- AI Generator → Services: calls · AI generation requests are sent to the backend
- Server Entry → API Routes: wires · Server bootstraps the route layer
- Server Entry → Auth Middleware: installs · Middleware is attached at server startup
- API Routes → Services: delegates · Routes keep logic thin and forward to services
- Services → Database Layer: reads/writes · Services persist data through the database layer
- Services → Gemini API: calls · AI service integration for generated tasks
- Auth Middleware → Auth Provider: verifies · Backend trusts an external identity source
- Database Layer → PostgreSQL: stores in · Drizzle-backed persistence uses PostgreSQL
- API Routes → Response Utils: formats · Endpoints use shared response envelopes
- Services → Response Utils: returns · Service results feed standard API responses