System Overview
Last verified: 2026-02-21 | 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 16.11, Webpack 4, Redux 4, TypeScript 3.7 | 8080 | Equity management SPA (cap table, ESOP, agreements, documents, finance, admin) | Active — 24 frontend modules |
| 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 | Balancing-Rock/command-center-so | Next.js 16.1, React 19, Tailwind CSS 4 | 3001 (next dev -p 3001) | AI chat UI, agent monitoring, settings, priority stack management | Active |
| 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 | 3333 | 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)
24 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 |
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/:
| 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) |
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-333648330110.us-central1.run.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)
equa-web/nginx.conf lines 13-19 (proxy config), equa-server/modules/api/src/server.ts line 180 (startApi function).
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 connects to the gateway for AI chat and agent management:- 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
command-center-so/src/app/api/chat/route.ts lines 14-17 (gateway config), command-center-so/railway.toml lines 11-14 (env vars).
Attachment Support by Route
The Command Center chat supports file and image attachments, but behavior varies by routing path:| 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/api/tasks/stack canonical normalization adapter. 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: command-center-so/src/app/api/tasks/stack/route.ts (stack adapter), 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 | equa-web/ | Active | |
| 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 |
| command-center-so | npm run dev (Next.js) | 3001 |
| equabot-gateway | equabot gateway start | 18789 |
| Ollama | System service | 11434 |
/api to localhost:3000. The Command Center reads EQUABOT_GATEWAY_URL=http://localhost:18789 from .env.local.
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 16.11 + Redux 4 + Redux Loop | equa-web/package.json |
| Frontend routing | React Router v5 + connected-react-router | equa-web/package.json |
| State management | Redux + redux-thunk + redux-loop | equa-web/src/logic/store.ts |
| Styling | styled-components 4 + 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 | Next.js 16.1 + React 19 + Tailwind CSS 4 | command-center-so/package.json |
| Container runtime | Node 18 Alpine (backend), Nginx Alpine (frontend) | equa-server/Dockerfile, equa-web/Dockerfile |