> ## 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.

# Architecture for Newcomers

> How the Equa platform is structured -- system diagram, modules, and data flows

# Architecture for Newcomers

> **Last Verified:** February 2026

This is a simplified overview of the Equa platform architecture, designed to help new engineers understand how the system is organized and where to find things. For deeper technical detail, see the forthcoming Phase 1 Architecture documentation.

## System Diagram

```mermaid theme={null}
graph TD
    Browser["Browser"]
    EquaWeb["equa-web :8080<br/>React 16 + Webpack 4"]
    EquaServer["equa-server :3000<br/>Express + TypeORM"]
    PostgreSQL["PostgreSQL :5432<br/>Docker"]
    EquabotGW["equabot-gateway :18789<br/>AI Agent Infrastructure"]
    Storybook["Storybook :6006<br/>Component Library"]
    
    Browser --> EquaWeb
    Browser --> Storybook
    EquaWeb -->|"API proxy /api/*"| EquaServer
    EquaServer --> PostgreSQL
    EquabotGW -->|"WebSocket + REST"| EquaServer

    subgraph externalSvc ["External Services"]
        GDrive["Google Drive"]
        MSGraph["Microsoft Graph"]
        Chargify["Chargify (Billing)"]
        CloudStorage["AWS S3 / GCS"]
        Claude["Claude AI"]
    end

    EquaServer --> GDrive
    EquaServer --> MSGraph
    EquaServer --> Chargify
    EquaServer --> CloudStorage
    EquabotGW --> Claude
```

## Frontend Modules

equa-web organizes features into 24 modules under `equa-web/src/modules/`. Each module typically contains its own components, services, and (in some cases) Redux store slices.

| Module                   | Purpose                                                         |
| ------------------------ | --------------------------------------------------------------- |
| `actions`                | Action item management                                          |
| `admin`                  | Administrative functionality and settings                       |
| `agreements`             | Equity agreements creation and management                       |
| `auth`                   | Login, registration, Google OAuth, password recovery            |
| `captable`               | Cap table management -- shareholders, shares, rounds            |
| `convertibles`           | Convertible instruments (SAFEs, notes)                          |
| `documents`              | Document management and templates                               |
| `equanaut`               | AI assistant chat interface (connects to equabot-gateway)       |
| `esop`                   | Employee Stock Option Plan administration                       |
| `google-drive`           | Google Drive file sync integration                              |
| `guest`                  | Guest user / limited access views                               |
| `hh-finance`             | Finance dashboard -- transactions, bank accounts, aging reports |
| `landing`                | Marketing landing page                                          |
| `organization`           | Organization creation and settings                              |
| `organization-dashboard` | Organization-level analytics dashboard                          |
| `payments`               | Payment processing                                              |
| `profile`                | User profile management                                         |
| `referrals`              | Referral program                                                |
| `reports`                | Reporting and analytics                                         |
| `roles`                  | Role management and permissions UI                              |
| `subscriptions`          | Subscription and billing management                             |
| `team-members`           | Team member invitations and management                          |
| `user-dashboard`         | User-level dashboard (cross-org view)                           |
| `welcome`                | Onboarding and welcome flow for new users                       |

Source: `equa-web/src/modules/` directory listing

## Backend Modules

equa-server uses Yarn workspaces with 20 modules under `equa-server/modules/`. Each module is a separate package with its own `package.json`, `src/` directory, and TypeScript config.

| Module          | Purpose                                                                                 |
| --------------- | --------------------------------------------------------------------------------------- |
| `api`           | Main entry point, endpoint registration, HTTP handlers                                  |
| `api-helper`    | Shared HTTP handler utilities used across modules                                       |
| `auth`          | Authentication (login/logout, sessions), authorization (roles, permissions), encryption |
| `persistence`   | Database schema (TypeORM entities), queries, migrations -- the data layer               |
| `captable`      | Cap table business logic (shareholdings, rounds, transactions)                          |
| `organizations` | Organization CRUD and settings                                                          |
| `billing`       | Chargify subscription and billing integration                                           |
| `file-storage`  | File upload and retrieval from S3 or GCS                                                |
| `notifications` | Email sending via SES, SMTP, or Mandrill                                                |
| `agent`         | AI assistant backend (Equanaut) -- Claude integration                                   |
| `doc-gen`       | Document generation from templates                                                      |
| `data-room`     | Data room document sharing and access control                                           |
| `google-drive`  | Google Drive sync (currently disabled)                                                  |
| `microsoft`     | Microsoft authentication and file operations                                            |
| `activity`      | Activity event tracking and logging                                                     |
| `admin`         | Admin-specific business logic                                                           |
| `referral`      | Referral program logic                                                                  |
| `common`        | Shared utilities, type interfaces, logging (Winston)                                    |
| `raven`         | Raven address management                                                                |
| `wallet`        | Wallet functionality                                                                    |

Source: `equa-server/modules/` directory listing

## Key Data Flows

### Authentication Flow

```mermaid theme={null}
sequenceDiagram
    participant B as Browser
    participant FE as equa-web
    participant BE as equa-server
    participant DB as PostgreSQL

    B->>FE: Navigate to /login
    FE->>BE: POST /v1/auth/login (email, password)
    BE->>DB: Verify credentials
    DB-->>BE: User record
    BE-->>FE: Session cookie + user data
    FE-->>B: Redirect to dashboard
    B->>FE: Subsequent requests
    FE->>BE: GET /v1/... (with session cookie)
    BE->>DB: Query data
    DB-->>BE: Results
    BE-->>FE: JSON response
```

Source: `equa-server/modules/auth/src/` for authentication logic; session-based auth using Express sessions

### Cap Table CRUD

1. User interacts with the cap table UI (`equa-web/src/modules/captable/`)
2. Frontend calls REST endpoints (`POST /v1/captable/...`)
3. equa-server's `api` module routes to the `captable` module
4. `captable` module uses `persistence` module to read/write TypeORM entities
5. Data stored in PostgreSQL

Source: `equa-server/modules/captable/` for business logic, `equa-server/modules/persistence/src/entity/` for entity definitions

### File Upload

1. User selects file in frontend
2. Frontend sends multipart upload to `POST /v1/files/upload`
3. `file-storage` module processes the upload
4. File stored in AWS S3 or Google Cloud Storage (configured via `STORAGE_TYPE` env var)
5. Database record created linking the file to its owner entity

Source: `equa-server/modules/file-storage/`

### Equanaut AI Chat

1. User opens chat in `equa-web/src/modules/equanaut/`
2. Frontend connects to equabot-gateway via WebSocket (port 18789)
3. Gateway routes the message to Claude API
4. Response streamed back through WebSocket to frontend

Source: `equabot-gateway/src/gateway/` for protocol handling

## Where Does X Live?

| Question                                             | Answer                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------- |
| Where are database entities defined?                 | `equa-server/modules/persistence/src/entity/`                             |
| Where is the full database schema?                   | `equa-server/modules/persistence/src/schema.ts` (2100+ lines)             |
| Where are API endpoints registered?                  | `equa-server/modules/api/src/endpoints/`                                  |
| Where is the auth middleware?                        | `equa-server/modules/auth/src/`                                           |
| Where are email templates?                           | `equa-server/modules/notifications/src/templates/`                        |
| Where is the cap table logic?                        | `equa-server/modules/captable/src/`                                       |
| Where are React components shared across modules?    | `equa-web/src/shared/components/`                                         |
| Where are global styles defined?                     | `equa-web/src/shared/styles/`                                             |
| Where is the Redux store?                            | `equa-web/src/logic/` (legacy -- being phased out)                        |
| Where are API service calls made?                    | `equa-web/src/service/`                                                   |
| Where is the AI agent config?                        | `equabot-gateway/src/agents/`                                             |
| Where are gateway protocol schemas?                  | `equabot-gateway/src/gateway/protocol/schema/`                            |
| Where are design system components?                  | `equa-patternlib-nextjs/src/components/`                                  |
| Where are Storybook stories?                         | `equa-patternlib-nextjs/stories/`                                         |
| Where is the spequa spec process for command center? | `command-center-so/.specify/` (legacy path) or `command-center-so/specs/` |

## Path Aliases (equa-web)

equa-web uses TypeScript path aliases so you don't need long relative imports. These are defined in `equa-web/tsconfig.json`:

| Alias           | Resolves To               | Example Usage                                        |
| --------------- | ------------------------- | ---------------------------------------------------- |
| `@src/*`        | `src/*`                   | `import { App } from '@src/app/App'`                 |
| `@modules/*`    | `src/modules/*`           | `import { CaptableView } from '@modules/captable'`   |
| `@shared/*`     | `src/shared/*`            | `import { Layout } from '@shared/components/Layout'` |
| `@components/*` | `src/shared/components/*` | `import { Button } from '@components/Button'`        |
| `@helpers/*`    | `src/shared/helpers/*`    | `import { formatDate } from '@helpers/dates'`        |
| `@styles/*`     | `src/shared/styles/*`     | `import { theme } from '@styles/theme'`              |
| `@image/*`      | `src/assets/image/*`      | `import logo from '@image/logo.svg'`                 |
| `@config/*`     | `config/*`                | `import config from '@config/local.json'`            |
| `@logic`        | `src/logic/`              | `import { store } from '@logic'`                     |

Source: `equa-web/tsconfig.json` paths configuration

## Architecture Patterns

**equa-server** uses these key patterns:

* **Modular monolith:** Each domain is a separate Yarn workspace package, but they deploy as a single process
* **vineyard-lawn:** A custom REST framework that provides endpoint decorators, validation, and routing on top of Express
* **Repository pattern:** Data access goes through the `persistence` module rather than calling TypeORM directly from business logic
* **Service layer:** Business logic lives in module `src/` directories, HTTP concerns in the `api` module endpoints

**equa-web** uses:

* **Module pattern:** Features are self-contained under `src/modules/` with their own components, services, and routes
* **Redux (legacy):** Older modules use Redux for state management; newer code prefers React hooks and local state
* **styled-components:** CSS-in-JS for component-scoped styling with a global ThemeProvider

For more depth, the Phase 1 Architecture documents (forthcoming) will cover the data model, entity relationships, permission system, and infrastructure in detail.