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

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

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 spec-kit process for command center?	command-center-so/.specify/

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.