Frontend Architecture

Repository: equa-web | Stack: React 18.2, TypeScript 5.3, Redux 4, Webpack 4 Last updated: 2026-04-11 (Phase 1 React 18 upgrade, ecosystem libraries, bundle optimization, API client network-error handling, dashboard empty state, gateway token sync)

Entry Point

Source: equa-web/src/index.tsx and equa-web/lab/main-prod.ts The app initializes polyfills (core-js/stable + regenerator-runtime/runtime), creates a Redux store via newStore(), creates browser history with createBrowserHistory(), wraps in a Redux Provider, and renders to #root via createRoot() from react-dom/client (upgraded from ReactDOM.render() in PR #506).

Module Inventory

The frontend is organized into feature modules under equa-web/src/modules/:

Module	Directory	Purpose
admin	`modules/admin/`	Admin dashboard, user management, site stats
agreements	`modules/agreements/`	Governing documents management
auth	`modules/auth/`	Login, registration, password reset, email verification
captable	`modules/captable/`	Cap table management, shareholdings, certificates
convertibles	`modules/convertibles/`	Convertible instruments and notes
documents	`modules/documents/`	Data room and document management
equanaut	`modules/equanaut/`	AI agent integration, action executor, onboarding
esop	`modules/esop/`	Employee stock option plans, pools, vesting schedules
google-drive	`modules/google-drive/`	Google Drive sync integration
guest	`modules/guest/`	Guest user pages (portfolio, dashboard, referrals)
hh-finance	`modules/hh-finance/`	Finance dashboard, transactions, metrics
landing	`modules/landing/`	Landing page, auth modal
organization	`modules/organization/`	Organization management, securities, legends
organization-dashboard	`modules/organization-dashboard/`	Organization dashboard, capital summary, empty-state onboarding guide
actions	`modules/actions/`	Organization actions, feature requests
payments	`modules/payments/`	Billing, payment profiles, checkout, subscriptions
profile	`modules/profile/`	User profile, portfolio, wallet, account settings
referrals	`modules/referrals/`	Referral system, EquaCash transfers
reports	`modules/reports/`	Reports (holder, pools, holdings)
roles	`modules/roles/`	Role management, permissions
subscriptions	`modules/subscriptions/`	Subscription management
team-members	`modules/team-members/`	Team member management, invitations
user-dashboard	`modules/user-dashboard/`	User dashboard
welcome	`modules/welcome/`	Onboarding flow, profile building, PIN setup

Routing and Code Splitting

Source: equa-web/src/app/routes/routes.ts, equa-web/src/app/routes/lazy.tsx, equa-web/src/app/components/routes/routes.tsx

Router: React Router v5 (react-router-dom 5.1.2) with redux-first-history (replaced connected-react-router in PR #465)
Route groups: profileRoutes, guestRoutes, guestOrganizationsRoutes, organizationListRoutes, organizationRoutes, routes
Protection: Routes flagged as protected redirect unauthenticated users
HOCs: withNavigation, withTracker, withService, withHeader, withOrganizationHeader, withProfileHeader
Path constants: equa-web/src/logic/paths.ts

Lazy Loading (Spec 050)

All feature module page components are lazy-loaded via React.lazy() + <Suspense>. The lazyPage() utility in src/app/routes/lazy.tsx wraps each dynamic import with a <Suspense> fallback using the existing <Loading /> spinner component.

const CaptablePage = lazyPage(() =>
  import('@modules/captable').then(m => ({ default: m.CaptablePage }))
)

What stays in the main bundle (static imports):

Auth module (@modules/auth/pages) — needed for login page to render immediately
Shell components: headers, navigation, loading, error boundary, permissions HOCs
Redux reducers (all 10 registered at store initialization per clarification C5)

What is lazy-loaded (137 dynamic imports across 25+ module groups):

All other page components: captable, ESOP, organization, convertibles, payments, profile, guest, admin, referrals, reports, roles, documents, welcome, team-members, hh-finance, google-drive, equabot-settings, agreements, landing, marketing, messaging, user-dashboard, organization-dashboard

The production build produces 48+ JS chunks: 4 named entrypoint chunks (react-vendor, styled, vendor, main) plus 4 async vendor chunks (crypto-vendor, pixi-vendor, form-vendor, pdf-vendor) plus ~40 lazy module chunks.

Chunk Error Boundary

Source: equa-web/src/app/components/routes/chunk-error-boundary.tsx A ChunkErrorBoundary wraps the route <Switch> in routes.tsx. If a lazy chunk fails to load (network error, deployment mismatch), it catches the error via getDerivedStateFromError and renders a “Failed to load this page” message with a Retry button instead of a white screen.

Adding New Routes

When adding a new route or module page:

Always use lazyPage() for the component import — never add a static import from a module barrel
Follow the pattern: const NewPage = lazyPage(() => import('@modules/new-module').then(m => ({ default: m.NewPage })))
The only exception is @modules/auth/pages which must stay static for the login critical path

State Management

Source: equa-web/src/logic/store.ts, equa-web/src/logic/reducers/root-reducer.ts

Component	Library	Version
Store	Redux	4.0.1
React bindings	react-redux	^8.1.0
Async actions	redux-thunk	2.3.0
Side effects	redux-loop	4.5.4
Router sync	redux-first-history	^5.x
DevTools	Redux DevTools Extension	—

Reducers

Reducer	Purpose
`userReducer`	Current user state, auth status
`organizationReducer`	Active organization data
`accessReducer`	Permissions and access control
`toastsReducer`	Toast notification queue
`myReferralReducer`	Referral program state
`capTableReducer`	Cap table data cache
`checklistReducer`	Onboarding checklist progress
`serviceReducer`	API service configuration

API Communication

Source: equa-web/src/service/lib/http-client.ts, equa-web/src/service/services/web-client.ts

HTTP client: Native fetch() for standard requests, axios 0.21.1 for multipart/form-data
Base URL: Configured via API_URL (default: /api/v1)
Credentials: credentials: 'include' (session cookies)
Error handling: HttpError class with auto-logout on 401
Methods: get(), post(), patch(), put(), delete(), postMultipart(), postFiles()

Network Error Handling (PR #514)

baseRequest() in http-client.ts wraps every fetch() call in a try-catch. When the backend is unreachable — DNS failure, CORS block, connection refused, offline — fetch() throws a TypeError. Rather than letting that throw propagate as an unhandled rejection (which was the root cause of the infinite splash screen bug, issue #482), the client converts it into a structured error:

return new HttpError(ResponseCode.other, 'networkError', /* ... */)

This lets the normal redux-loop failure path dispatch, the getCurrentUser callback fires, initialLoad flips to true, and the app renders the login page instead of hanging on the Equa logo spinner forever. Callers do not need special handling — the network-error response follows the same HttpError contract as 4xx/5xx responses. Anywhere the code already checks isHttpError(result), the network-error case is handled automatically. Source: equa-web/src/service/lib/http-client.ts (PR #514, 2026-04-02).

Service modules

Located in equa-web/src/service/services/:

actions, billing, captable, google-drive, organizations, payments, profile, roles, wallet

Component Library

Source: equa-web/package.json (dependency: equa-patternlib from GitHub) The pattern library provides 26+ shared UI components: Avatar, Badge, Button, Card, Checkbox, Chip, DatePicker, Dropdown, FileUpload, Input, Menu, Modal, Pagination, Progress, Radio, Rating, Sidebar, Skeleton, Slider, Stepper, Switch, Table, Tabs, Toast, Toggle, Tooltip Components are re-exported via equa-web/src/shared/components/.

Styling

Approach	Library	Source
Primary	styled-components ^6.1.0	`equa-web/src/styles/styled.ts`
Global styles	`createGlobalStyle`	`equa-web/src/styles/global.ts`
Theme	ThemeProvider	`equa-web/src/styles/theme.ts`
Utilities	polished 3.4.1	Color manipulation
SCSS	sass-loader (webpack)	Legacy components

Theme switching is supported and persisted via cookies.

Font Loading

Six NunitoSans variants are declared via @font-face in src/styles/global.ts. All declarations include font-display: swap to prevent Flash of Invisible Text (FOIT). When adding new @font-face rules, always include font-display: swap.

styled-components Build Plugin

The babel-plugin-styled-components (^2.1.4) is active in the webpack babel-loader config. In production builds it strips displayName and enables pure annotation for dead code elimination. In development it preserves displayName for debugging.

Webpack Configuration

Source: equa-web/webpack.config.js

Setting	Value
Entry	`lab/main-prod.ts`
Output	`dist/` with content hashes (`[name]-[hash].js`)
Dev server port	8080
API proxy	`/api` -> `http://localhost:3000`
Equanaut proxy	`/equanaut-api` -> `http://localhost:19792`
Production minifier	TerserPlugin
Bundle analyzer	`ANALYZE_BUNDLE=1` env var triggers `webpack-bundle-analyzer`
Babel plugins	`babel-plugin-styled-components` (production: `displayName: false, pure: true`)

splitChunks (Production Only)

The production build uses cacheGroups to separate vendor code into named chunks for optimal caching: Initial chunks (loaded on every page):

Cache Group	Name	Priority	Content
`react`	`react-vendor`	20	react, react-dom, react-router, react-redux, redux
`styled`	`styled`	15	styled-components
`vendor`	`vendor`	10	All other initial `node_modules`

Async chunks (loaded on-demand when navigating to specific routes):

Cache Group	Name	Priority	Content	Loaded When
`crypto`	`crypto-vendor`	25	ethers, web3, crypto libs (18 KB)	Wallet/MetaMask pages
`pixi`	`pixi-vendor`	25	pixi.js-legacy (629 KB)	Chart/visualization pages
`form`	`form-vendor`	15	react-select, react-datepicker	Pages with form components
`pdf`	`pdf-vendor`	15	react-pdf, pdfjs-dist	Document viewer pages

Additional settings: maxInitialRequests: 10, minSize: 20000. The async vendor chunks were added in PR #510 to reduce the initial page load by ~2.5 MB — pixi.js, crypto libs, and the login background image (compressed 95% from 1.93 MB to 93 KB) are no longer loaded on first visit.

Performance Budgets

Budget	Value	Mode
Max entrypoint size	500 KB	`warning`
Max asset size	300 KB	`warning`

These budgets emit build warnings for oversized chunks. The entrypoint size was significantly reduced in PR #510 by moving heavy vendor libraries to async chunks (~2.5 MB reduction). Further reduction requires upgrading to Webpack 5 (better tree shaking) or migrating to Vite (Phase 2).

Polyfill Strategy

The entry point imports core-js/stable and regenerator-runtime/runtime (replacing the deprecated @babel/polyfill). The @babel/preset-env handles transpilation targeting browsers specified in the webpack config.

Path Aliases

Alias	Maps To
`@src`	`src/`
`@logic`	`src/logic`
`@config`	`local.json`
`@styles`	`src/shared/styles`
`@modules`	`src/modules`
`@components`	`src/shared/components`
`@shared`	`src/shared`
`@helpers`	`src/shared/helpers`
`@image`	`src/assets/image`

Key Utilities

Utility	File	Purpose
Type helpers	`src/shared/helpers/util.ts`	Uuid, Hash, Money, formatting
Validators	`src/shared/helpers/field-validators.ts`	Form field validation
Data cache	`src/shared/helpers/data-cache.ts`	Client-side caching
Shareholdings	`src/shared/helpers/shareholdings.ts`	Shareholding calculations
MS Graph	`src/shared/helpers/ms/msGraph.ts`	Microsoft integration
Constants	`src/shared/helpers/constants.tsx`	App-wide constants

Coding Conventions

Lodash Imports

Use per-function imports, never the full library:

import range from 'lodash/range'
import isEqual from 'lodash/isEqual'

Never use import _ from 'lodash' — this pulls the entire 72 KB library into the bundle even if only one function is used. If a file doesn’t actually call any lodash function, remove the import entirely.

Route Imports

All page component imports in routes.ts must use lazyPage() dynamic imports. The only exception is @modules/auth/pages (static for the login critical path). See Routing and Code Splitting above.

Dependency Hygiene

Before adding a new dependency, check if it will end up in the initial entrypoint bundle or a lazy chunk. Heavy libraries (>100 KB) should only be imported from lazy-loaded modules. The following unused packages were removed during Spec 050 and must not be re-added: moment (use date-fns instead), recharts, react-hot-loader, @hot-loader/react-dom.

Testing

Framework	Purpose
Jest 29 + React Testing Library 14	Unit tests (migrated from Jest 26 + Enzyme in PR #465)
Playwright	E2E tests (`e2e/` directory)
Visual regression	Screenshot comparison in CI (PR #509)

Performance Testing

Source: Comet-Bridge/scripts/perf-audit.mjs An automated performance audit script runs via Comet-Bridge Playwright against the equa-web dev server or production build. It navigates all major route groups, captures performance.timing metrics (TTI, DCL, load time), checks for chunk load errors, and produces a JSON report with screenshots.

cd Comet-Bridge
node scripts/perf-audit.mjs --url http://localhost:8080
node scripts/perf-audit.mjs --url http://localhost:8090 --throttle  # fast 3G

Output: ~/.claude/comet-browser/output/audit/s050-perf/perf-report.json

​Frontend Architecture

​Entry Point

​Module Inventory

​Routing and Code Splitting

​Lazy Loading (Spec 050)

​Chunk Error Boundary

​Adding New Routes

​State Management

​Reducers

​API Communication

​Network Error Handling (PR #514)

​Service modules

​Component Library

​Styling

​Font Loading

​styled-components Build Plugin

​Webpack Configuration

​splitChunks (Production Only)

​Performance Budgets

​Polyfill Strategy

​Path Aliases

​Key Utilities

​Coding Conventions

​Lodash Imports

​Route Imports

​Dependency Hygiene

​Testing

​Performance Testing