How riteshpanchal279/ai-task-manager works
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: TaskDashboard.tsx Task Dashboard · services Services · routes API Routes · task.ts Task Types
Components 20
Frontend
Next.js client app and dashboard UI
- App Router · Next.js app entry, layout, and page shell
frontend/src/app - Task Dashboard · Main task workspace and orchestration component
frontend/src/components/TaskDashboard.tsx - Auth Guard · Client-side route and session gating
frontend/src/components/AuthGuard.tsx - useTasks · Task fetching and mutation state management
frontend/src/hooks/useTasks.ts - Task List · Task list and item presentation
frontend/src/components/TaskList.tsx - Task Form · Create and edit task form flows
frontend/src/components/TaskForm.tsx - Edit Dialog · Task editing dialog wrapper
frontend/src/components/TaskEditDialog.tsx - Stats Cards · Dashboard metrics and progress cards
frontend/src/components/StatsCards.tsx - AI Generator · Task generation UI for suggested tasks
frontend/src/components/AITaskGenerator.tsx - UI Primitives · Shared shadcn-style UI building blocks
frontend/src/components/ui - Task Types · Frontend task data shape shared across components
frontend/types/task.ts
Backend
Node.js API with routes, services, and database access
- Server Entry · Backend server startup and wiring
backend/src/index.ts - API Routes · Domain route handlers for tasks, users, and stats
backend/src/routes - Services · Application logic for tasks, users, and AI generation
backend/src/services - Auth Middleware · Server-side identity and access protection
backend/src/middleware/auth.ts - Database Layer · Drizzle configuration and PostgreSQL schema access
backend/src/db - Response Utils · Shared response formatting helpers
backend/src/utils/response.ts
External
Outside services consumed by the backend
- PostgreSQL · Persistent task and user data store
- Gemini API · External model API used for task generation
- Auth Provider · External authentication source such as Clerk or Firebase
Connections 22
- 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