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
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 |
package.json for framework versions; port numbers from dev server configs and server.ts entry points.
Frontend Modules (equa-web)
Documented frontend modules inequa-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 |
equa-web/src/modules/ directory listing.
Backend Modules (equa-server)
20 Yarn workspace packages inequa-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 |
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
/apitohttp://localhost:3000(equa-server) - Production: Nginx proxies
/api/tohttps://equa-server-so-production.up.railway.app/ - API base URL:
/api/v1(configurable viaAPI_URLenv var) - Authentication: Session-based — cookies with
credentials: 'include'on all fetch requests - Endpoint framework: vineyard-lawn (custom Express routing layer)
/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-29equa-web/webpack.config.js, Lines: 95-103, 262-266equa-server/modules/api/src/server.ts, Line: 180
equa-web ↔ equa-patternlib
The design system is consumed as a direct GitHub dependency: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 fromhttp://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_URLenv var (default:http://localhost:18789) - Authentication: Bearer token via
EQUABOT_GATEWAY_TOKENenv 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
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 frozencommand-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 |
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 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
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
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 | Primary user authentication | equa-server/modules/auth/ | Active | |
| Drive API | 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 | 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 | Usage analytics | equa-web/ (react-ga) | Active |
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 |
/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)
Phase 3: Production Cloud Deployment (Future)
Redeployment toequa.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 |
| 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 |