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

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

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

Cap Table CRUD

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

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

File Upload

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

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

Equanaut AI Chat

User opens chat in equa-web/src/modules/equanaut/
Frontend connects to equabot-gateway via WebSocket (port 18789)
Gateway routes the message to Claude API
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.

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Architecture for Newcomers

Architecture for Newcomers

System Diagram

Frontend Modules

Backend Modules

Key Data Flows

Authentication Flow

Cap Table CRUD

File Upload

Equanaut AI Chat

Where Does X Live?

Path Aliases (equa-web)

Architecture Patterns

​Architecture for Newcomers

​System Diagram

​Frontend Modules

​Backend Modules

​Key Data Flows

​Authentication Flow

​Cap Table CRUD

​File Upload

​Equanaut AI Chat

​Where Does X Live?

​Path Aliases (equa-web)

​Architecture Patterns

Architecture for Newcomers

System Diagram

Frontend Modules

Backend Modules

Key Data Flows

Authentication Flow

Cap Table CRUD

File Upload

Equanaut AI Chat

Where Does X Live?

Path Aliases (equa-web)

Architecture Patterns