rajat-wyrm/apogee

1. Repository shape

- This is a monorepo with a Node/Express backend at the root and a React/Vite frontend in apps/web.

- The architecture is clearly split into a server API, a browser client, shared operational scripts, and an extensive integration test suite.

2. Backend entry and request pipeline

- The backend starts from src/index.js, with configuration in src/config, database access in src/db, middleware in src/middleware, and feature routes under src/modules/*/routes.js.

- Incoming HTTP requests flow through middleware first, then into domain modules, then to database/service layers.

- The middleware layer includes authentication, rate limiting, and caching, which are architectural concerns rather than feature code.

3. Domain-driven API layout

- The backend is organized by business capability: auth, organizations, workspaces, projects, tasks, documents, files, analytics, AI, billing, admin, notifications, teams, search, wiki, whiteboards, calendar, goals, automations, exports, webhooks, presence, sharing, and more.

- Each module owns its REST endpoints, which makes the API surface easy to diagram as a set of bounded contexts behind the same Express server.

4. Multi-tenant and access-control boundaries

- The product is multi-tenant: organizations and workspaces are the core isolation units.

- Auth, role-based access control, and tenant-aware database access are central boundaries; most routes are authenticated, and admin routes are explicitly separated.

- The README indicates tenant isolation is enforced at the query layer, so the diagram should show tenancy being validated server-side, not just in the UI.

5. Data layer and migrations

- PostgreSQL is the primary persistent store, accessed through src/db/pool.js.

- Schema evolution is explicit via SQL schema files (schema.sql, schema-phase2.sql, schema-advanced.sql) and migration scripts (scripts/migrate.js, src/db/migrate.js).

- There is also a seed script (scripts/seed.js) that bootstraps demo data, showing the app expects a structured DB setup before the API runs.

6. Service layer and external integrations

- Cross-cutting backend services live in src/services: AI, audit logging, email, files, notifications, cache, and tokens.

- These are where external dependencies matter: AI providers, email delivery, file storage (Cloudinary), billing (Stripe), and notification dispatch are abstracted away from route handlers.

- src/utils/crypto.js and src/utils/http.js support lower-level security and HTTP concerns.

7. Real-time subsystem

- Socket.IO is a separate subsystem under src/sockets, with its own setup and server wiring.

- It appears to power live notifications and presence-style collaboration, complementing the REST API rather than replacing it.

- In a diagram, this is a second inbound channel alongside HTTP, sharing auth/context with the backend but serving push updates.

8. Frontend application structure

- The frontend entry is apps/web/src/main.jsx, with the UI built from pages, features, components, layouts, store, hooks, lib, and theme.

- pages represent route-level screens, features group business domains, and components contain reusable UI primitives and shells.

- This suggests a composition model: page → feature → shared component, rather than a tightly coupled SPA.

9. Client-side state and API access

- apps/web/src/lib/api.js is the primary HTTP client boundary to the backend, and apps/web/src/lib/socket.js is the client connection for real-time events.

- Zustand stores in apps/web/src/store handle auth, organization/workspace context, and theme.

- The frontend therefore has two major outbound dependencies: REST for data mutation/query and Socket.IO for live updates.

10. UI shell and navigation

- The app has a reusable application shell (AppLayout, Layout, Sidebar, Topbar, WorkspaceSwitcher, command palette, drawers, etc.) that wraps the feature pages.

- There are separate auth layouts/screens for login, registration, forgot password, and two-factor flows.

- This is important for the diagram because authenticated product flows and unauthenticated onboarding flows are structurally distinct.

11. Product surface areas on the client

- The frontend mirrors the backend domains: dashboard, projects, tasks, documents, whiteboards, wiki, calendar, notifications, reports, billing, admin, settings, team, search, automations, goals, and helpdesk.

- Many of these are likely feature views backed by the matching API module, so the safest diagram is a one-to-one alignment of client feature areas to backend route modules.

12. Operational and delivery concerns

- Docker is first-class: there are separate Dockerfiles for backend and frontend, plus docker-compose.yml.

- CI is handled through GitHub Actions (.github/workflows/ci.yml), and Jest/Supertest provide integration coverage for the backend contract.

- The frontend also has PWA-oriented setup via Vite config and manifest assets, indicating offline-capable browser behavior is part of the delivery model.

13. Main end-to-end data flow

- A user interacts with the React app, which reads auth/org state from client stores, calls the Express API via lib/api.js, and subscribes to Socket.IO for live events.

- The backend authenticates and authorizes the request, resolves the tenant/workspace context, performs DB operations in PostgreSQL, and may invoke services for files, email, billing, AI, or notifications.

- The result is returned synchronously over HTTP and, when relevant, broadcast asynchronously over sockets.

14. What to emphasize in an architecture diagram

- Show three major zones: browser frontend, Node/Express backend, PostgreSQL data store.

- Add side integrations for Socket.IO, AI providers, Stripe, Cloudinary, and email/notification services.

- Inside the backend, depict middleware, domain modules, and shared services as the main internal boundaries; inside the frontend, depict layouts/shell, page-level features, shared components, and client state/API layers.