# realsalman/synapse-ai-task-manager architecture

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

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

## Overview

1. **Overall shape**
   - This is a split full-stack monorepo: a **Next.js frontend** in `client/` and a **Node/Express backend** in `server/`.
   - The product is a **task/board manager with AI assistance**, not just a CRUD app: the UI has board management, task details, and an AI chat/workflow layer.

2. **Frontend application boundary**
   - The frontend uses the **Next.js App Router** under `client/app/`.
   - Route structure suggests three major areas:
     - public auth screens: `/login`, `/register`
     - a user-scoped dashboard: `/[uid]`
     - nested board views: `/[uid]/b/[boardUrlID]/[boardName]`
   - This implies the UI is organized around a user identifier and board-specific deep links.

3. **Frontend composition**
   - Shared shell components live in `client/components/`:
     - `Navbar`, `Sidebar`, `Board`, `ErrorNavbar`
     - skeleton/loaders for dashboard, navbar, sidebar, boards, and board content
   - Modal and drawer UI are first-class:
     - board/task CRUD modals in `client/modals/`
     - AI chat drawer and related AI UI in `client/components/ai/`
   - This suggests a highly interactive single-page experience embedded inside the Next.js app.

4. **Client state and data boundaries**
   - The frontend separates responsibilities across several state layers:
     - `context/AuthContext.tsx` for authentication/session state
     - `context/ThemeContext.tsx` for theming
     - `providers/QueryProvider.tsx` for **TanStack Query** server-state fetching/caching
     - Zustand stores in `client/store/` for local app/UI state, including AI-related state
   - `client/hooks/useBoards.ts` likely wraps remote board fetching/mutations, so board data is treated as server state rather than local UI state.

5. **Frontend external integration**
   - `client/lib/firebaseConfig.ts` indicates the browser app connects directly to **Firebase Authentication**.
   - `client/lib/api.ts` is the API client boundary to the backend, likely attaching auth tokens and normalizing HTTP calls.
   - This creates a clear split: **Firebase handles identity**, while the backend handles domain data and persistence.

6. **Backend architecture**
   - The backend’s primary implementation is in `server/src/` and follows a standard layered structure:
     - `routes/` define HTTP endpoints
     - `controllers/` contain request handling
     - `models/` define MongoDB/Mongoose entities
     - `middleware/` handles auth and request protection
     - `services/` encapsulate AI/business logic
     - `config/` holds DB setup
   - There are also older JS files at `server/` root (`server.js`, `routes/`, `models/`, `db.js`), but the TypeScript `src/` tree appears to be the main architecture.

7. **Backend domain models**
   - The MongoDB models show the core domain objects:
     - `user.model.ts`
     - `userBoards.model.ts`
     - `AIChat.model.ts`
     - `AIAction.model.ts`
   - That means persistence is not only for users and boards, but also for AI conversation history and AI-driven actions.

8. **Backend request flow**
   - Requests enter through `server/src/index.ts`, then route modules such as:
     - `users.routes.ts`
     - `boards.routes.ts`
     - `ai.routes.ts`
   - `auth.middleware.ts` indicates protected routes verify Firebase-based identity before hitting controllers.
   - Controllers then read/write MongoDB models and return data to the Next.js client.

9. **AI subsystem**
   - AI is a separate backend concern, not embedded directly in the frontend.
   - `server/src/services/aiTools.service.ts` and `ai.controller.ts` suggest the backend orchestrates AI calls and tool-like actions.
   - The README’s `OPENROUTER_API_KEY` confirms the AI layer integrates with **OpenRouter** for model access.
   - The frontend AI drawer/chat tabs/model selector work as the user-facing shell for this backend AI subsystem.

10. **Authentication and identity flow**
   - Firebase is the authentication provider on the client side, with Firebase Admin configured on the server.
   - The likely flow is:
     - user signs in/registers in the browser via Firebase
     - client sends Firebase auth token to the API
     - server verifies token in middleware
     - backend maps the Firebase identity to internal MongoDB user records
   - This avoids custom password handling in the backend and centralizes trust in Firebase.

11. **Task/board data flow**
   - Board and task interactions are likely:
     - UI triggers mutations from board components and modals
     - API client sends requests to the Express backend
     - backend persists board/task state in MongoDB `userBoards` documents
     - query hooks refresh the view via TanStack Query
   - The presence of dedicated loaders and a board-specific route tree suggests data is fetched incrementally as users move between dashboard and board detail views.

12. **Infrastructure and runtime**
   - Frontend runtime: **Next.js/React** with Tailwind CSS.
   - Backend runtime: **Node.js/Express** with **TypeScript**.
   - Data stores/services: **MongoDB**, **Firebase Auth/Admin**, and **OpenRouter** for AI.
   - Environment configuration is split cleanly:
     - backend `.env` for MongoDB, Firebase service account, OpenRouter, port
     - frontend `.env.local` for API base URL and Firebase client config

13. **What to emphasize in an architecture diagram**
   - Show three major boundaries:
     - browser UI layer (Next.js app, state providers, AI/chat/board components)
     - API layer (Express controllers/routes, auth middleware, AI service)
     - persistence/integration layer (MongoDB, Firebase Auth/Admin, OpenRouter)
   - The most important data paths are:
     - authenticated user/session flow via Firebase
     - board/task CRUD flow via API to MongoDB
     - AI chat/action flow via backend AI service to OpenRouter and back to persisted chat/action records

Main entry points: [`server/src/controllers`](https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/controllers) (Controllers), [`client/app`](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/app) (Next.js app), [`client/components/ai`](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/components/ai) (AI drawer), [`server/src/routes`](https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/routes) (HTTP routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_client_app["Next.js app<br/>frontend"]
  node_client_shell["UI shell<br/>layout/components"]
  node_client_ai_ui["AI drawer<br/>interaction UI"]
  node_client_modals["Board modals<br/>interaction UI"]
  node_client_state["Client state<br/>state layer"]
  node_client_api["API client<br/>data client<br/>[api.ts]"]
  node_client_firebase["Firebase config<br/>auth client<br/>[firebaseConfig.ts]"]
  node_client_boards_hook["Boards hook<br/>data hook<br/>[useBoards.ts]"]
end

subgraph group_server["API server"]
  node_server_entry["API entry<br/>server bootstrap<br/>[index.ts]"]
  node_server_routes["HTTP routes<br/>routing"]
  node_server_controllers["Controllers<br/>request handlers"]
  node_server_auth["Auth middleware<br/>security<br/>[auth.middleware.ts]"]
  node_server_models["Mongo models<br/>persistence models"]
  node_server_ai_service["AI service<br/>business logic<br/>[aiTools.service.ts]"]
end

subgraph group_integrations["External services"]
  node_mongo[("MongoDB<br/>database")]
  node_firebase_auth(("Firebase Auth<br/>identity provider"))
  node_firebase_admin(("Firebase Admin<br/>server identity SDK"))
  node_openrouter(("OpenRouter<br/>ai provider"))
end

node_client_app -->|"renders"| node_client_shell
node_client_app -->|"opens"| node_client_modals
node_client_app -->|"hosts"| node_client_ai_ui
node_client_shell -->|"reads"| node_client_state
node_client_ai_ui -->|"uses"| node_client_state
node_client_modals -->|"mutates"| node_client_boards_hook
node_client_boards_hook -->|"calls"| node_client_api
node_client_state -->|"authenticates"| node_client_firebase
node_client_api -->|"requests"| node_server_entry
node_server_entry -->|"mounts"| node_server_routes
node_server_routes -->|"protects"| node_server_auth
node_server_routes -->|"dispatches"| node_server_controllers
node_server_controllers -->|"reads/writes"| node_server_models
node_server_controllers -->|"orchestrates"| node_server_ai_service
node_server_models -->|"persists"| node_mongo
node_server_auth -->|"verifies"| node_firebase_admin
node_firebase_admin -.->|"trusts"| node_firebase_auth
node_server_ai_service -->|"invokes"| node_openrouter
node_server_controllers -.->|"maps identity"| node_firebase_admin
node_client_ai_ui -->|"chat/action flow"| node_server_ai_service

click node_client_app "https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/app"
click node_client_shell "https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/components"
click node_client_ai_ui "https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/components/ai"
click node_client_modals "https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/modals"
click node_client_state "https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/context"
click node_client_api "https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/lib/api.ts"
click node_client_firebase "https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/lib/firebaseConfig.ts"
click node_client_boards_hook "https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/hooks/useBoards.ts"
click node_server_entry "https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/index.ts"
click node_server_routes "https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/routes"
click node_server_controllers "https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/controllers"
click node_server_auth "https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/middleware/auth.middleware.ts"
click node_server_models "https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/models"
click node_server_ai_service "https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/services/aiTools.service.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_client_app,node_client_shell,node_client_ai_ui,node_client_modals,node_client_state,node_client_api,node_client_firebase,node_client_boards_hook toneBlue
class node_server_entry,node_server_routes,node_server_controllers,node_server_auth,node_server_models,node_server_ai_service toneAmber
class node_mongo,node_firebase_auth,node_firebase_admin,node_openrouter toneMint
```

## Components

### Client app

Next.js frontend, UI state, and user interaction layer.

- [Next.js app](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/app): frontend · App Router entrypoints and route-level screens for auth, dashboard, and boards. · `client/app`
- [UI shell](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/components): layout/components · Shared navigation, sidebar, board shell, and page scaffolding. · `client/components`
- [AI drawer](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/components/ai): interaction UI · Chat drawer, model picker, chat tabs, and action history for AI-assisted workflows. · `client/components/ai`
- [Board modals](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/modals): interaction UI · Task, board, and column dialogs used for create, edit, and delete flows. · `client/modals`
- [Client state](https://github.com/realsalman/synapse-ai-task-manager/tree/main/client/context): state layer · Auth, theme, query, and local UI stores that coordinate browser state. · `client/context`
- [API client](https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/lib/api.ts): data client · Browser API boundary used to call the backend and attach session context. · `client/lib/api.ts`
- [Firebase config](https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/lib/firebaseConfig.ts): auth client · Client-side Firebase setup for sign-in and token acquisition. · `client/lib/firebaseConfig.ts`
- [Boards hook](https://github.com/realsalman/synapse-ai-task-manager/blob/main/client/hooks/useBoards.ts): data hook · Board fetching and mutation hook that bridges UI actions to server state. · `client/hooks/useBoards.ts`

### API server

Express backend with routes, controllers, auth, and services.

- [API entry](https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/index.ts): server bootstrap · Express startup and request entrypoint for the TypeScript backend. · `server/src/index.ts`
- [HTTP routes](https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/routes): routing · Versioned route modules for users, boards, and AI endpoints. · `server/src/routes`
- [Controllers](https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/controllers): request handlers · Request orchestration for users, boards, and AI operations. · `server/src/controllers`
- [Auth middleware](https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/middleware/auth.middleware.ts): security · Token verification and protected-route guard for Firebase-backed identity. · `server/src/middleware/auth.middleware.ts`
- [Mongo models](https://github.com/realsalman/synapse-ai-task-manager/tree/main/server/src/models): persistence models · User, board, chat, and AI action schemas used for MongoDB persistence. · `server/src/models`
- [AI service](https://github.com/realsalman/synapse-ai-task-manager/blob/main/server/src/services/aiTools.service.ts): business logic · Backend AI orchestration and tool execution used by the chat subsystem. · `server/src/services/aiTools.service.ts`

### External services

Identity, database, and AI dependencies.

- **MongoDB**: database · Primary persistence store for users, boards, chats, and AI actions.
- **Firebase Auth**: identity provider · Authentication provider used by the browser client and verified by the server.
- **Firebase Admin**: server identity SDK · Server-side Firebase integration for token verification and user trust.
- **OpenRouter**: ai provider · External model access used by the backend AI layer.

## Connections

- Next.js app → UI shell: renders · Route screens compose the shared application shell.
- Next.js app → Board modals: opens · Board and task screens trigger CRUD dialogs.
- Next.js app → AI drawer: hosts · The app includes the AI interaction surface alongside board workflows.
- UI shell → Client state: reads · Shell components depend on auth, theme, and UI state.
- AI drawer → Client state: uses · AI drawer and related widgets consume local and global client state.
- Board modals → Boards hook: mutates · Dialogs invoke board/task mutations through the boards hook.
- Boards hook → API client: calls · Board operations flow through the API client.
- Client state → Firebase config: authenticates · Auth context integrates with Firebase sign-in and session state.
- API client → API entry: requests · The browser sends domain requests to the Express backend.
- API entry → HTTP routes: mounts · The server initializes route modules at startup.
- HTTP routes → Auth middleware: protects · Protected routes verify identity before reaching handlers.
- HTTP routes → Controllers: dispatches · HTTP endpoints delegate to request controllers.
- Controllers → Mongo models: reads/writes · Controllers persist domain data through Mongo models.
- Controllers → AI service: orchestrates · AI endpoints and related flows call backend AI logic.
- Mongo models → MongoDB: persists · Mongoose models store application data in MongoDB.
- Auth middleware → Firebase Admin: verifies · Backend middleware validates Firebase identity tokens.
- Firebase Admin → Firebase Auth: trusts · Server-side verification is anchored in Firebase-issued identity.
- AI service → OpenRouter: invokes · AI orchestration uses OpenRouter for model access.
- Controllers → Firebase Admin: maps identity · User and protected-board flows associate Firebase identities with backend users.
- AI drawer → AI service: chat/action flow · The AI drawer drives backend-assisted chat and action execution.