Backend Architecture

Repository: equa-server | Stack: Express, TypeORM, PostgreSQL, Node 18, vineyard-lawn

Server Entry Point

Source: equa-server/modules/api/src/server.ts (function startApi(), lines 180-198) The server starts with this sequence:

Create Express app
Enable CORS via enableCors(app) (vineyard-lawn)
Initialize sessions via initializeSessions() (TypeORM session store)
Register Google OAuth redirect endpoint
Register all API endpoints via createEndpoints(app, endpoints) (vineyard-lawn)
Initialize dynamic file serving
Register /health and / ping endpoints
Register 404 handler
Start Express on configured port (default: 3000)

SSL Support

Source: equa-server/modules/api/src/server.ts (function startExpress(), lines 53-98) SSL is optional, activated when API_SSL env var is set. Reads certs from SSL_PRIVATE_KEY_PATH and SSL_PUBLIC_KEY_PATH.

Module Inventory

The backend is organized into 20 modules under equa-server/modules/:

Module	Directory	Purpose
api	`modules/api/`	Main Express server, endpoint registration, route definitions
api-helper	`modules/api-helper/`	HTTP handler utilities, response formatting
auth	`modules/auth/`	Authentication (password, Google OAuth, magic links), sessions, RBAC
persistence	`modules/persistence/`	TypeORM entities (92), database connection, schema management
organizations	`modules/organizations/`	Organization CRUD, details, settings
captable	`modules/captable/`	Cap table management, shareholdings, securities
billing	`modules/billing/`	Chargify billing integration, subscriptions
notifications	`modules/notifications/`	Email via AWS SES / SMTP, Handlebars templates
file-storage	`modules/file-storage/`	AWS S3 file upload/download, Microsoft file storage
doc-gen	`modules/doc-gen/`	Document generation (certificates, agreements)
data-room	`modules/data-room/`	Data room access control and file management
google-drive	`modules/google-drive/`	Google Drive OAuth, sync, file operations
microsoft	`modules/microsoft/`	Microsoft Graph integration
admin	`modules/admin/`	Admin-only endpoints
activity	`modules/activity/`	Activity/action logging
agent	`modules/agent/`	AI assistant (Equanaut) — chat, tools, onboarding
referral	`modules/referral/`	Referral system, EquaCash rewards
wallet	`modules/wallet/`	Wallet and payment method management
common	`modules/common/`	Shared types and utilities
raven	`modules/raven/`	Raven blockchain address management

Endpoint Framework: vineyard-lawn

Endpoints are defined using vineyard-lawn’s type-safe endpoint system. Source: equa-server/modules/api/src/lib/utility.ts (lines 60-94)

// Standard endpoint
defineEndpoint<T>(config)

// Endpoint with permission check
defineRestrictedEndpoint<T>(config)

Each endpoint specifies:

HTTP method and path
Request/response types
Optional requires?: PermissionCheck for authorization
Versioning (v1 prefix)

Endpoint Files

Source: equa-server/modules/api/src/endpoints/

File	Endpoint Group
`auth-endpoints.ts`	Authentication (login, register, verify, OAuth)
`organization-endpoints.ts`	Organization CRUD, details, settings
`captable-endpoints.ts`	Cap table operations, shareholdings
`user-endpoints.ts`	User management, profile, current user
`billing-endpoints.ts`	Billing, subscriptions, Chargify webhooks
`admin-endpoints.ts`	Admin-only operations
`activity-endpoints.ts`	Activity logging and retrieval
`data-room-endpoints.ts`	Data room access and files
`google-drive-endpoints.ts`	Google Drive sync and connection
`microsoft-endpoints.ts`	Microsoft integration
`referral-endpoints.ts`	Referral system
`wallet-endpoint.ts`	Wallet and blockchain operations
`color-endpoints.ts`	User color preferences

Agent-specific endpoints in equa-server/modules/agent/src/endpoints/:

agent-endpoints.ts — Chat, confirmations, context, tools, onboarding

Database Layer

Source: equa-server/modules/persistence/src/site/connecting.ts

Property	Value
ORM	TypeORM
Database	PostgreSQL (configurable via `DATABASE_TYPE`)
Entities	92 (defined in `schema.ts`)
Schema sync	Enabled in development (`NODE_ENV=development && DATABASE_SYNC !== 'false'`)
Connection config	Via environment variables (`DATABASE_HOST`, `DATABASE_USERNAME`, etc.)

Entity Registration

Source: equa-server/modules/persistence/src/schema.ts (lines 2008-2101) All 92 entities are registered in the allEntities array and loaded during connection initialization.

Middleware Stack

Middleware	Purpose	Source
CORS	Cross-origin requests	vineyard-lawn `enableCors()`
express-session	Session management	`modules/auth/src/sessions.ts`
TypeORM session store	Session persistence in PostgreSQL	Custom `TypeORMSessionStore`
URL-encoded parser	Google OAuth redirect	`server.ts` line 143
Error logging	Request error capture	`configureErrorLogging()`

No explicit rate limiting middleware was found in the codebase. This is a gap for production readiness.

Process Architecture

Development

equa-server $ yarn start:dev
→ ts-node modules/api/scripts/api.ts
→ Express on port 3000

Production

Docker (node:18-alpine)
→ PM2 (pm2-runtime)
  → api process (./modules/api/scripts/api.js, port 3000)
  → raven-addresses process (./modules/raven/scripts/user-raven-addresses.js)

Build Pipeline

Source: equa-server/package.json

Script	Command
`build`	`yarn tsc && yarn tsa`
`tsc`	Build API module TypeScript
`tsa`	Build file-storage module TypeScript
`start:api`	`yarn build && cd modules/api && node scripts/api.js`
`start:dev`	Development mode with ts-node
`init:db`	Database initialization

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Backend Architecture

Backend Architecture

Server Entry Point

SSL Support

Module Inventory

Endpoint Framework: vineyard-lawn

Endpoint Files

Database Layer

Entity Registration

Middleware Stack

Process Architecture

Development

Production

Build Pipeline

​Backend Architecture

​Server Entry Point

​SSL Support

​Module Inventory

​Endpoint Framework: vineyard-lawn

​Endpoint Files

​Database Layer

​Entity Registration

​Middleware Stack

​Process Architecture

​Development

​Production

​Build Pipeline

Backend Architecture

Server Entry Point

SSL Support

Module Inventory

Endpoint Framework: vineyard-lawn

Endpoint Files

Database Layer

Entity Registration

Middleware Stack

Process Architecture

Development

Production

Build Pipeline