> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # System Overview > Component architecture, service topology, integration points, and build path for the integrated Equa platform # System Overview > **Last verified:** 2026-03-29 | **Sources:** All repository `package.json` files, deployment configs, and server entry points cited inline below ## Integrated Equa Vision Equa is a commercial equity management platform spanning multiple repositories that are all modules of a **single integrated application**. The repositories are not independent products — they are components in different stages of integration building toward one seamless Equa App experience. The build path is: local development (all services on one machine) → Mac/iOS Desktop App (native container) → `equa.cc` production deployment (cloud hosting, TBD). *** ## Component Diagram ```mermaid theme={null} graph TD subgraph userFacing [User-Facing Applications] EquaWeb["equa-web\n(React 18 SPA, :8080)"] CommandCenter["Command Center\n(equa-web full-screen Equanaut mode)"] CommandCenterSource["command-center-so\n(frozen source material, :3001 legacy)"] DesktopApp["equa-desktop-app\n(Mac/iOS — planned)"] end subgraph backend [Backend Services] EquaServer["equa-server\n(Express + TypeORM, :3000)"] Gateway["equabot-gateway\n(AI Agent, :18789)"] CometBridge["Comet-Bridge\n(Browser Automation, CDP :9222)"] end subgraph sharedLibs [Shared Libraries] PatternLib["equa-patternlib-nextjs\n(React components + design tokens)"] end subgraph dataLayer [Data Layer] PostgreSQL["PostgreSQL\n(92+ entities via TypeORM)"] S3["AWS S3\n(file storage)"] end subgraph externalServices [External Services] GoogleOAuth["Google OAuth"] GoogleDrive["Google Drive API"] MicrosoftGraph["Microsoft Graph API"] Chargify["Chargify\n(billing/subscriptions)"] SES["AWS SES\n(email)"] Ollama["Ollama\n(local LLM, :11434)"] Tailscale["Tailscale\n(remote access)"] MattermostServer["Mattermost\n(team messaging, :8065)"] end EquaWeb -->|"npm dep from GitHub"| PatternLib EquaWeb -->|"/api/ proxy via nginx"| EquaServer EquaWeb -->|"Command Center mode"| CommandCenter CommandCenter -->|"Gateway/BFF + bearer token auth"| Gateway CommandCenterSource -.->|"legacy source material"| CommandCenter CommandCenterSource -.->|"OpenAI/Ollama direct source material"| Ollama Gateway -->|"WebSocket + HTTP"| Tailscale DesktopApp -.->|"planned integration"| EquaWeb DesktopApp -.->|"planned integration"| Gateway EquaServer --> PostgreSQL EquaServer --> S3 EquaServer --> GoogleOAuth EquaServer --> GoogleDrive EquaServer --> MicrosoftGraph EquaServer --> Chargify EquaServer --> SES EquaServer -->|"REST API (admin bot token)"| MattermostServer Gateway --> Ollama CommandCenterSource -.->|"browser task source material"| CometBridge Gateway -->|"CDP sessions"| CometBridge ``` *** ## Service Inventory | Component | Repository | Framework | Port | Purpose | Status | | ----------------------------- | ------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- | | **Equa Web** | `EQUAStart/equa-web` | React 18.2, Webpack 4, Redux 4, TypeScript 5.3 | 8080 | Equity management SPA (cap table, ESOP, agreements, documents, finance, admin) | Active | | **Equa Server** | `EQUAStart/equa-server` | Express 4, TypeORM 0.2, PostgreSQL, Node 18 | 3000 | Backend API — authentication, data persistence, business logic, file storage | Active — 20 backend modules | | **Equa Patternlib** | `EQUAStart/equa-patternlib-nextjs` | React 18, Next.js 14, Storybook 8.4 | 3333 (Next.js) / 6006 (Storybook) | Shared design system — 30+ React components, design tokens | Active | | **Command Center** | `EQUAStart/equa-web` | React 18.2, Webpack 4, TypeScript 5.3 | 8080 (`/prime?openEquanaut=true`, rail mode on app routes) | Full-screen Equanaut mode for AI chat, agent monitoring, settings, priority stack management | Active | | **Command Center Source App** | `EQUAStart/equanaut-command-center-main` | Next.js 16.1, React 19, Tailwind CSS 4 | 3001 legacy | Frozen source material for parity checks; not the supported local route | Frozen | | **Equabot Gateway** | `EQUAStart/equabot` | TypeScript (ESM), Bun, Lit Web Components | 18789 (WS) / 18791 (Browser Ctrl) | Local-first AI agent — LLM orchestration, channel routing, tool execution, session management | Active | | **Comet-Bridge** | `Balancing-Rock/Comet-Bridge` | Node.js (ESM), MCP server, Playwright | 9222 (CDP) | Persistent browser automation — Perplexity Comet, tab-group isolation, multi-agent safety, audit trails | Active | | **Equa Docs** | `equa-docs` | Mintlify | 3337 | Platform documentation site (this repo) | Active | | **Desktop App** | `equa-desktop-app-mac-ios` | Planned: SwiftUI (Mac/iOS) | — | Native Mac/iOS app container wrapping Equa web + gateway integration | Planned (repo empty) | | **Priority Stack** | `Balancing-Rock/stacks-ranking-priorities` | — | — | Task management and priority ranking system | Active | **Source:** Each repository's `package.json` for framework versions; port numbers from dev server configs and `server.ts` entry points. *** ## Frontend Modules (equa-web) Documented frontend modules in `equa-web/src/modules/`: | Module | Purpose | | ------------------------ | -------------------------------------------------------------- | | `actions` | Organization actions and workflows | | `admin` | Site administration, user management | | `agreements` | Governing documents management | | `auth` | Login, register, password reset, email verification | | `captable` | Cap table management, shareholdings, certificates | | `convertibles` | Convertible instruments/notes | | `documents` | Data room and document management | | `equanaut` | AI assistant integration | | `esop` | Equity plans, option pools, vesting schedules | | `google-drive` | Google Drive file sync | | `guest` | Public-facing pages for unauthenticated users | | `hh-finance` | Finance dashboard and transactions | | `landing` | Public landing page | | `messaging` | Mattermost team messaging (iframe embed, session provisioning) | | `organization` | Organization management, securities, legends | | `organization-dashboard` | Organization-level dashboard | | `payments` | Billing, payment profiles | | `profile` | User profile, wallet, portfolio, account settings | | `referrals` | Referral system, Equa Cash transfers | | `reports` | Holder, holdings, and pool reports | | `roles` | Role management and permissions | | `subscriptions` | Subscription management | | `team-members` | Team member management, invitations | | `user-dashboard` | User-level dashboard | | `welcome` | Onboarding flow | **Source:** `equa-web/src/modules/` directory listing. *** ## Backend Modules (equa-server) 20 Yarn workspace packages in `equa-server/modules/` (plus the `mattermost` submodule inside `agent`): | Module | Purpose | | --------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `api` | Express server entry, endpoint registration, request handlers | | `api-helper` | Common HTTP handler utilities | | `activity` | Event logging and activity tracking | | `admin` | Admin-specific business logic | | `agent` | AI agent endpoints (Equanaut onboarding, context); contains `mattermost` submodule for team messaging provisioning and org sync | | `auth` | Authentication (Google OAuth, email/password, magic links, 2FA), authorization (RBAC) | | `billing` | Chargify subscription management | | `captable` | Cap table business logic | | `common` | Shared types, interfaces, logging (Winston) | | `data-room` | Data room functionality | | `doc-gen` | Document generation | | `file-storage` | AWS S3 file upload/download/sync | | `google-drive` | Google Drive file sync (endpoints currently commented out) | | `microsoft` | Microsoft Azure AD OAuth, Graph API integration | | `notifications` | Email via AWS SES (primary) / SMTP (fallback) | | `organizations` | Organization management logic | | `persistence` | TypeORM schema (92+ entities), database helpers, migrations | | `raven` | Raven address service integration | | `referral` | Referral system logic | | `wallet` | Wallet and payment method management | **Source:** `equa-server/modules/` directory listing and each module's `package.json`. *** ## Integration Points ### equa-web ↔ equa-server The frontend communicates with the backend via a reverse proxy: * **Development:** Webpack dev server proxies `/api` to `http://localhost:3000` (equa-server) * **Production:** Nginx proxies `/api/` to `https://equa-server-so-production.up.railway.app/` * **API base URL:** `/api/v1` (configurable via `API_URL` env var) * **Authentication:** Session-based — cookies with `credentials: 'include'` on all fetch requests * **Endpoint framework:** vineyard-lawn (custom Express routing layer) Browser traffic still uses the same-origin `/api/v1` path; the hostname `api.equa.cc` may exist for direct callers, but it is not the proxy target declared in the committed nginx config. **Sources:** * `equa-web/nginx.conf`, Lines: 21-29 * `equa-web/webpack.config.js`, Lines: 95-103, 262-266 * `equa-server/modules/api/src/server.ts`, Line: 180 ### equa-web ↔ equa-patternlib The design system is consumed as a direct GitHub dependency: ```json theme={null} "equa-patternlib": "github:EQUAStart/equa-patternlib-nextjs#master" ``` Webpack is configured with a special babel-loader rule to transpile the patternlib's TypeScript/TSX source. equa-web re-exports patternlib components through wrappers in `equa-web/src/shared/components/` (tooltip, toggle, toast, tabs, tables, switch). **Source:** `equa-web/package.json` (dependency), `equa-web/webpack.config.js` (babel-loader rules for patternlib). ### Command Center ↔ Equabot Gateway The Command Center is the expanded full-page Equanaut mode inside equa-web. Locally it opens from `http://localhost:8080/prime?openEquanaut=true` or from the Equanaut rail on `/fleet`, `/admin`, `/ai`, and `/equabotz`. The old `http://localhost:3001/command-center` split-origin app is frozen source material, not the supported local route. * **Gateway URL:** `EQUABOT_GATEWAY_URL` env var (default: `http://localhost:18789`) * **Authentication:** Bearer token via `EQUABOT_GATEWAY_TOKEN` env var * **Chat endpoint:** Gateway's `/v1/responses` (OpenResponses API) * **Fallback routes:** Command Center can call OpenAI API and Ollama directly, bypassing the gateway * **System prompt:** Built from workspace files (`SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`, `MEMORY.md`, etc.) cached for 5 minutes **Source:** `equa-web/specs/060-command-center-fleet-management-shell/spec.md`, `equa-web/src/modules/equanaut/index.tsx`, `equa-web/src/modules/equanaut/components/CommandCenterPanel.tsx`, and frozen source material in `command-center-so/src/app/api/chat/route.ts`. #### Attachment Support by Route The frozen `command-center-so` source app documented the attachment behavior below. Treat it as source material for parity checks until each route is verified in the current equa-web Command Center surface: | Route | Images | Non-image files | Notes | | ------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | **Local (Ollama) — vision model** | Sent via Ollama `images` array (base64) | Not processed; descriptive note appended to message | Vision models: names matching `llava`, `bakllava`, or `vision` | | **Local (Ollama) — non-vision model** | Attach buttons disabled in UI | Attach buttons disabled in UI | Tooltip: "Attachments not supported for this model. Switch to OpenAI or gateway." | | **OpenAI direct** | Inline base64 (`input_image`) | Uploaded to `/v1/files`, sent as `input_file` (fallback: error text on upload failure) | Full attachment support | | **Gateway** | Inline base64 (`input_image`) | Inline base64 (`input_file`) | Actual support depends on gateway upstream model | | **Fallback (gateway error → local)** | Same as local vision | Same as local (note only) | Triggered on gateway 429/5xx or streaming errors | **Source:** `command-center-so/src/app/api/chat/route.ts` (attachment routing logic), `command-center-so/src/app/page.tsx` line 1046 (capability detection). ### Command Center ↔ GitHub Projects The Command Center ingests Task Thread data from a GitHub Project (24-field schema) through the priority-stack adapter exposed to equa-web status surfaces. Priority, Status, Stack Rank, and Urgency values from the project are authoritative — the UI computes display-only decorations but does not override the normalized API payload. See [Command Center — Task Stack Contract](/web/command-center#task-stack-contract) for the full field inventory, identity model, blocker convention, and runtime mapping. **Source:** `equa-web/src/modules/equanaut/hooks/useOrchestration.ts`, `command-center-so/src/app/api/tasks/stack/route.ts` (frozen adapter source material), `command-center-so/src/lib/types.ts` (TaskThread type). ### Gateway ↔ Equa Platform (Future Integration) The Equabot gateway is currently a self-contained local-first system with **no direct connection** to equa-server or equa-web. The gateway manages its own messaging channels (Telegram, Google Chat, Discord, etc.), AI providers, and tool execution independently. Integration between the gateway and the Equa platform is planned but not yet implemented. The desktop app will serve as the native container that unifies both systems. *** ## Data Flow: User Request Lifecycle ```mermaid theme={null} sequenceDiagram participant Browser participant Nginx as Nginx / Webpack Proxy participant Express as Express Server (:3000) participant VineyardLawn as vineyard-lawn Router participant AuthMiddleware as Session Auth participant Handler as Endpoint Handler participant PostgreSQL as PostgreSQL Browser->>Nginx: HTTPS request to /api/v1/* Nginx->>Express: Proxy to equa-server Express->>VineyardLawn: Route matching (/v1/ prefix) VineyardLawn->>AuthMiddleware: Session validation AuthMiddleware->>PostgreSQL: Check sessions table PostgreSQL-->>AuthMiddleware: Session data (user ID) AuthMiddleware->>VineyardLawn: User authenticated VineyardLawn->>Handler: Call endpoint handler Handler->>PostgreSQL: Query/mutation via persistence helpers PostgreSQL-->>Handler: Result Handler-->>Browser: JSON response ``` **Source:** `equa-server/modules/api/src/server.ts` lines 180-198 (`startApi` initialization order: sessions → Google auth redirect → endpoints → file serving → health → root ping → 404). *** ## Data Flow: Authentication ```mermaid theme={null} sequenceDiagram participant Browser participant EquaWeb as equa-web participant EquaServer as equa-server participant Google as Google OAuth participant PostgreSQL as PostgreSQL Browser->>EquaWeb: Click "Sign in with Google" EquaWeb->>Google: Redirect to Google consent screen Google-->>EquaWeb: Return ID token (credential) + CSRF token EquaWeb->>EquaServer: POST /v1/user/google-auth/redirect (form-urlencoded) EquaServer->>EquaServer: Validate CSRF (body vs cookie) EquaServer->>Google: Verify ID token via tokeninfo API Google-->>EquaServer: Token verified (email, sub) EquaServer->>PostgreSQL: Find or create user by email EquaServer->>PostgreSQL: Create session in Sessions table EquaServer-->>Browser: Redirect to /login?authenticated=true (set session cookie) ``` **Source:** `equa-server/modules/api/src/server.ts` lines 142-178 (`initializeGoogleAuthRedirect`), `equa-server/modules/auth/src/google-auth.ts`. *** ## External Services Map | Service | Provider | Purpose | Module | Status | | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------- | | **S3** | AWS | File storage (uploads, data room documents) | `equa-server/modules/file-storage/` | Active | | **SES** | AWS | Transactional email (verification, notifications) | `equa-server/modules/notifications/` | Active (SMTP fallback) | | **OAuth** | Google | Primary user authentication | `equa-server/modules/auth/` | Active | | **Drive API** | Google | File sync with Google Drive | `equa-server/modules/google-drive/` | Module exists, endpoints commented out | | **Azure AD + Graph** | Microsoft | Secondary auth, file uploads, group drives | `equa-server/modules/microsoft/` | Conditional (requires `MS_AUTH_CLIENT_ID` env var) | | **Chargify** | Maxio | Billing, subscriptions, payment management | `equa-server/modules/billing/` | Active | | **Ollama** | Local | LLM inference (Qwen 72B, Llama 70B, DeepSeek) | Command Center direct + Gateway | Active (port 11434) | | **Tailscale** | Tailscale | Remote access to gateway via Serve/Funnel | Gateway config | Active | | **reCAPTCHA** | Google | Bot protection on auth forms (via `react-google-recaptcha`, migrated from `react-recaptcha-google` in PR #465; test key removed in PR #493) | `equa-web/` | Active — requires `CAPTCHA_SITE_KEY` env var | | **FullStory** | FullStory | Session recording/analytics | `equa-web/` | Configurable | | **Google Analytics** | Google | Usage analytics | `equa-web/` (react-ga) | Active | **Source:** Each service verified from import statements and configuration in the respective modules. *** ## Build Path ### Phase 1: Local Development (Current) All services run on a single development machine: | Service | Command | Port | | --------------- | --------------------------------- | ----- | | PostgreSQL | Docker container | 5432 | | equa-server | `yarn start:dev` | 3000 | | equa-web | `yarn start` (Webpack dev server) | 8080 | | equa-patternlib | `npm run storybook` | 6006 | | equabot-gateway | `equabot gateway start` | 18789 | | Ollama | System service | 11434 | The Webpack dev server proxies `/api` to `localhost:3000`. The Command Center opens inside the existing equa-web process and reaches the gateway through the same-origin API/BFF paths. ### Phase 2: Mac/iOS Desktop App (Planned) A native SwiftUI container app (`equa-desktop-app-mac-ios`) that integrates: * The Equa web app (embedded WebView or rebuilt in SwiftUI) * The Equabot gateway (local service) * The Command Center (agent management UI) This repo is currently empty. The target is a fully integrated local experience before any cloud deployment. ### Phase 3: Production Cloud Deployment (Future) Redeployment to `equa.cc` (or alternative hosting) once the integrated local version is perfected. Hosting platform TBD — options include GCP Cloud Run (prior deployment), Railway (configs already exist), or alternative. **Redeployment triggers:** Feature-complete local version, paying customer pipeline ready, funding available for hosting, hosting platform decision finalized. **Source:** Wind-down context from `equabot/threads/wind-down-equa-cc-public-instance/CONTEXT.md`. *** ## Key Technical Decisions | Decision | Choice | Source | | ------------------------- | ----------------------------------------------------- | --------------------------------------------------------------- | | Frontend framework | React 18.2 + Redux 4 + Redux Loop | `equa-web/package.json` | | Frontend routing | React Router v5 + redux-first-history | `equa-web/package.json` | | State management | Redux + redux-thunk + redux-loop | `equa-web/src/logic/store.ts` | | Styling | styled-components 6.1 + design tokens from patternlib | `equa-web/package.json`, `equa-patternlib-nextjs/src/tokens/` | | Forms | React Final Form 6.4 | `equa-web/package.json` | | Backend framework | Express + vineyard-lawn (custom routing) | `equa-server/modules/api/src/server.ts` | | ORM | TypeORM 0.2 (PostgreSQL) | `equa-server/modules/persistence/` | | Authentication | Session-based (express-session + TypeORM store) | `equa-server/modules/auth/` | | Process manager | PM2 (production) | `equa-server/ecosystem.config.js` | | File storage | AWS S3 (aws-sdk) | `equa-server/modules/file-storage/src/s3.d.ts` | | Email | AWS SES (primary), SMTP (fallback) | `equa-server/modules/notifications/` | | AI integration | Equabot gateway (local-first, multi-provider) | `equabot-gateway/src/gateway/server-http.ts` | | Command Center | equa-web React/TypeScript full-screen Equanaut mode | `equa-web/src/modules/equanaut/`, `equa-web/src/modules/prime/` | | Command Center Source App | Next.js 16.1 + React 19 + Tailwind CSS 4 | `command-center-so/package.json` (frozen source material) | | Container runtime | Node 18 Alpine (backend), Nginx Alpine (frontend) | `equa-server/Dockerfile`, `equa-web/Dockerfile` |