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

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:

"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 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	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`

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

System Overview

System Overview

Integrated Equa Vision

Component Diagram

Service Inventory

Frontend Modules (equa-web)

Backend Modules (equa-server)

Integration Points

equa-web ↔ equa-server

equa-web ↔ equa-patternlib

Command Center ↔ Equabot Gateway

Attachment Support by Route

Command Center ↔ GitHub Projects

Gateway ↔ Equa Platform (Future Integration)

Data Flow: User Request Lifecycle

Data Flow: Authentication

External Services Map

Build Path

Phase 1: Local Development (Current)

Phase 2: Mac/iOS Desktop App (Planned)

Phase 3: Production Cloud Deployment (Future)

Key Technical Decisions

​System Overview

​Integrated Equa Vision

​Component Diagram

​Service Inventory

​Frontend Modules (equa-web)

​Backend Modules (equa-server)

​Integration Points

​equa-web ↔ equa-server

​equa-web ↔ equa-patternlib

​Command Center ↔ Equabot Gateway

​Attachment Support by Route

​Command Center ↔ GitHub Projects

​Gateway ↔ Equa Platform (Future Integration)

​Data Flow: User Request Lifecycle

​Data Flow: Authentication

​External Services Map

​Build Path

​Phase 1: Local Development (Current)

​Phase 2: Mac/iOS Desktop App (Planned)

​Phase 3: Production Cloud Deployment (Future)

​Key Technical Decisions

System Overview

Integrated Equa Vision

Component Diagram

Service Inventory

Frontend Modules (equa-web)

Backend Modules (equa-server)

Integration Points

equa-web ↔ equa-server

equa-web ↔ equa-patternlib

Command Center ↔ Equabot Gateway

Attachment Support by Route

Command Center ↔ GitHub Projects

Gateway ↔ Equa Platform (Future Integration)

Data Flow: User Request Lifecycle

Data Flow: Authentication

External Services Map

Build Path

Phase 1: Local Development (Current)

Phase 2: Mac/iOS Desktop App (Planned)

Phase 3: Production Cloud Deployment (Future)

Key Technical Decisions