How realsalman/synapse-ai-task-manager works
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: controllers Controllers · app Next.js app · ai AI drawer · routes HTTP routes
Components 18
Client app
Next.js frontend, UI state, and user interaction layer.
- Next.js app · App Router entrypoints and route-level screens for auth, dashboard, and boards.
client/app - UI shell · Shared navigation, sidebar, board shell, and page scaffolding.
client/components - AI drawer · Chat drawer, model picker, chat tabs, and action history for AI-assisted workflows.
client/components/ai - Board modals · Task, board, and column dialogs used for create, edit, and delete flows.
client/modals - Client state · Auth, theme, query, and local UI stores that coordinate browser state.
client/context - API client · Browser API boundary used to call the backend and attach session context.
client/lib/api.ts - Firebase config · Client-side Firebase setup for sign-in and token acquisition.
client/lib/firebaseConfig.ts - Boards 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 · Express startup and request entrypoint for the TypeScript backend.
server/src/index.ts - HTTP routes · Versioned route modules for users, boards, and AI endpoints.
server/src/routes - Controllers · Request orchestration for users, boards, and AI operations.
server/src/controllers - Auth middleware · Token verification and protected-route guard for Firebase-backed identity.
server/src/middleware/auth.middleware.ts - Mongo models · User, board, chat, and AI action schemas used for MongoDB persistence.
server/src/models - AI service · 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 · Primary persistence store for users, boards, chats, and AI actions.
- Firebase Auth · Authentication provider used by the browser client and verified by the server.
- Firebase Admin · Server-side Firebase integration for token verification and user trust.
- OpenRouter · External model access used by the backend AI layer.
Connections 20
- 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.