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

# Coding Standards

> TypeScript conventions, linting, formatting, and patterns across Equa repositories

# Coding Standards

> **Last Verified:** February 2026

The Equa platform repositories use different toolchains that evolved independently. This guide documents the actual state of each repository's coding standards rather than presenting an idealized unified standard.

## Standards at a Glance

| Repository        | Linter             | Formatter              | TypeScript            | Module System | React Pattern      |
| ----------------- | ------------------ | ---------------------- | --------------------- | ------------- | ------------------ |
| equa-web          | TSLint 5.20        | Prettier (via TSLint)  | 3.7, strict           | CommonJS      | Class + hooks mix  |
| equa-server       | TSLint 5.20        | tslint-config-prettier | ES2019 target, strict | CommonJS      | N/A                |
| equabot-gateway   | Oxlint             | Oxfmt                  | ESM, strict           | ESM           | N/A                |
| equa-patternlib   | ESLint (next lint) | --                     | 5.0, strict           | ESM (Next.js) | Functional + hooks |
| command-center-so | ESLint (next lint) | --                     | 5.0, strict           | ESM (Next.js) | Functional + hooks |

Source: `package.json` and `tsconfig.json` files across repos

<Note>
  TSLint is deprecated and unmaintained. equa-web and equa-server still use it. An ESLint migration is recommended but has not been prioritized.
</Note>

## TypeScript Conventions

All repositories use TypeScript with `strict: true` enabled. Common rules that apply everywhere:

* **Avoid `any`** -- Use proper typing. If a type is unknown, prefer `unknown` and narrow it.
* **Prefer interfaces over type aliases** for object shapes (consistency with existing code).
* **Use `readonly` for immutable properties** where semantically appropriate.

### equa-web / equa-server (CommonJS)

* Module system: `"module": "commonjs"` in tsconfig
* Decorators: `"experimentalDecorators": true` -- used by TypeORM entities in equa-server and some patterns in equa-web
* Target: ES6 (equa-web), ES2019 (equa-server)

Source: `equa-web/tsconfig.json`, `equa-server/tsconfig.json`

### equabot-gateway (ESM)

* Module system: `"type": "module"` in package.json
* Target: Modern Node.js (22+)
* LOC guideline: Aim to keep files under \~500 lines; split/refactor when it improves clarity
* Strict typing enforced more aggressively than legacy repos

Source: `equabot-gateway/package.json`, `equabot/CLAUDE.md` coding style section

## React Patterns

### equa-web (Mixed Legacy and Modern)

equa-web has code spanning several years. You'll encounter two patterns:

**Legacy (older modules):**

* Class components with `React.Component`
* Redux for state management (`src/logic/` contains the store)
* `connected-react-router` for routing with Redux integration
* `react-final-form` for form handling

**Modern (newer code):**

* Functional components with hooks (`useState`, `useEffect`, `useContext`)
* Local state preferred over Redux
* React Router 5 for routing

**Guideline:** When writing new code in equa-web, prefer hooks and functional components. When modifying existing class components, match the existing pattern unless refactoring is the explicit goal.

### equa-patternlib / command-center-so (Modern)

* Functional components only
* React hooks for all state management
* No Redux

## Styling

### equa-web: styled-components 4.2

Components are styled using [styled-components](https://styled-components.com/) with a global ThemeProvider:

```typescript theme={null}
import styled from 'styled-components';
import { ThemeProps, Theme } from '@styles/theme';

const Container = styled.div`
  background-color: ${(props: ThemeProps<Theme>) => props.theme.backgroundDark};
  padding: 16px;
`;
```

Theme variables are defined in `equa-web/src/shared/styles/theme.ts`. Always prefer theme variables over hardcoded values for colors, spacing, and typography.

Global CSS styles: `equa-web/src/shared/styles/global.ts`

Source: `equa-web/README.md` (lines 37-44)

### equa-patternlib: styled-components 6.3

Same pattern but uses the newer styled-components API with React 18.

### command-center-so: Tailwind CSS 4

Uses utility-first CSS classes. No styled-components.

## Linting and Formatting

### equa-web

```bash theme={null}
# Check for linting errors
yarn tslint-check

# Auto-fix linting errors
yarn tslint
```

Config: `equa-web/tslint.json` extends `tslint:recommended` with Prettier integration.

Source: `equa-web/package.json` scripts

### equa-server

```bash theme={null}
# Lint all TypeScript files
yarn tslint
```

Config: `equa-server/tslint.json` uses `tslint-config-prettier`.

Source: `equa-server/package.json` scripts

### equabot-gateway

```bash theme={null}
# Lint (type-aware)
pnpm lint

# Format check
pnpm format

# Auto-fix lint + format
pnpm lint:fix
pnpm format:fix
```

Uses Oxlint for linting and Oxfmt for formatting. Run `pnpm lint` before commits.

Source: `equabot-gateway/package.json` scripts

### equa-patternlib / command-center-so

```bash theme={null}
# ESLint via Next.js
npm run lint    # or yarn lint
```

## File Organization

### Module Pattern (equa-web)

Each feature lives in its own module under `src/modules/`:

```
src/modules/captable/
├── components/       # React components specific to this feature
├── services/         # API calls for this feature
├── store/            # Redux actions/reducers (legacy modules only)
└── index.tsx         # Module entry point and route registration
```

### Workspace Module Pattern (equa-server)

Each module is a separate Yarn workspace package:

```
modules/captable/
├── src/
│   ├── endpoints/    # HTTP endpoint definitions (vineyard-lawn)
│   ├── services/     # Business logic
│   └── index.ts      # Module exports
├── package.json      # Module dependencies
└── tsconfig.json     # Extends root config
```

The `api` module registers all endpoint handlers. The `persistence` module owns all database entities and queries. Other modules reference persistence for data access.

### Colocated Tests (equabot-gateway)

Tests live alongside the code they test:

```
src/browser/
├── tab-group-title.ts
└── tab-group-title.test.ts
```

## Naming Conventions

These are observed patterns, not enforced rules:

| Element                | Convention               | Example                                  |
| ---------------------- | ------------------------ | ---------------------------------------- |
| Files (components)     | PascalCase or kebab-case | `CaptableView.tsx`, `tab-group-title.ts` |
| Files (utilities)      | kebab-case               | `format-date.ts`, `api-helper.ts`        |
| React components       | PascalCase               | `<ShareholderTable />`                   |
| Functions/variables    | camelCase                | `handleSubmit`, `isLoading`              |
| Constants              | UPPER\_SNAKE\_CASE       | `MAX_FILE_SIZE`, `API_BASE_URL`          |
| TypeORM entities       | PascalCase               | `Organization`, `ShareHolding`           |
| Database tables        | snake\_case              | `organization`, `share_holding`          |
| CSS classes (Tailwind) | kebab-case utilities     | `text-sm`, `bg-primary`                  |

## Recommendations

1. **Migrate equa-web and equa-server from TSLint to ESLint** -- TSLint has been deprecated since 2019. ESLint with `@typescript-eslint` is the modern standard.
2. **Standardize on a single formatting tool** -- Currently a mix of Prettier (via TSLint), Oxfmt, and no formatter. Consider Prettier or Biome across all repos.
3. **Adopt consistent path aliases** -- equa-web has path aliases; equa-server does not. Consistent `@` aliases would improve readability.