# WS Demo — Developer Handoff Guide

Use this guide to move from the interactive prototype to production **Spring Boot** (backend) and **React + Node.js** (frontend).

---

## Quick start

| Role | Start here |
|------|------------|
| **Backend** | [ARCHITECTURE.md](./ARCHITECTURE.md) §4, [openapi/ws-api-v3.yaml](./openapi/ws-api-v3.yaml), `js/platform/entity-schema.js` |
| **Frontend** | [MODULE-MAP.md](./MODULE-MAP.md), `js/navigation-data.js`, `css/kit-theme.css`, prototype screens in `js/modules/` |
| **Architect / TL** | [ENTITY-MODEL.md](./ENTITY-MODEL.md), `js/core/architecture.js` |

**Live prototype:** https://prototype.vdtcomms.com/ws-erp/demo/  
**Developer portal (in prototype):** `demo/developers.html` (source tree: `v3/`)

---

## Phase 1 — Repository bootstrap

### Backend (`ws-backend`)

1. Create Spring Boot 3.x multi-module project (see ARCHITECTURE.md package layout).
2. Import OpenAPI spec; generate DTOs or use springdoc.
3. Implement `ws-tenancy`:
   - `TenantContext` (ThreadLocal)
   - `TenantConnectionRouter` for `SHARED` vs `DEDICATED`
   - Servlet filter reading `X-WS-Tenant-Id`, `X-WS-Company-Id`
4. Base entity: `AbstractAuditableEntity` with UUID id + audit fields.
5. Seed reference data: currencies, platform applications.

### Frontend (`ws-frontend`)

1. Create Vite + React + TypeScript app.
2. Port design tokens from `v3/css/kit-theme.css` and `v3/css/ws-app.css`.
3. Implement shell: sidebar, pillar tabs, tenant/company switchers (mirror `js/core/app.js`).
4. Generate API client from OpenAPI or mirror `js/platform/api-client.js`.
5. Lazy-load feature modules matching `js/modules/*.js`.

---

## Phase 2 — Module port order (recommended)

| Order | Domain | Prototype file | API prefix |
|-------|--------|----------------|------------|
| 1 | Tenancy & session | `workspace-state.js`, `tenancy.js` | `/api/v1/auth`, `/api/v1/tenant/companies` |
| 2 | Structure | `modules/structure.js` | `/api/v1/structure/*` |
| 3 | Finance GL | `modules/finance-gl.js` | `/api/v1/finance/*` |
| 4 | Contacts | `modules/contacts-crm.js` | `/api/v1/contacts` |
| 5 | CRM | `modules/contacts-crm.js` | `/api/v1/crm/*` |
| 6 | Access | `modules/access-approval-platform-ops.js` | `/api/v1/access/*` |
| 7 | Approval | same | `/api/v1/approval/*` |
| 8 | Platform | same | `/api/v1/platform/*` |
| 9 | Operations | same | `/api/v1/operations/*` |

Each module: CRUD screens first, then process flows (e.g. journal post → approval).

---

## Phase 3 — Tenancy implementation checklist

### Shared database

- [ ] All tenant tables include `tenant_id UUID NOT NULL`
- [ ] Company-scoped tables include `company_id UUID NOT NULL`
- [ ] Repository methods always apply tenant (+ company) predicate
- [ ] Integration tests prove cross-tenant leakage is impossible

### Dedicated database

- [ ] `ws_tenant.database_mode` enum: `SHARED`, `DEDICATED`
- [ ] `ws_tenant.database_ref` points to connection config
- [ ] Router switches `DataSource` before `@Transactional`
- [ ] Migrations run per dedicated DB on provision

### Multi-company

- [ ] `ws_company` table per tenant
- [ ] User may access one or more companies (membership table)
- [ ] Active company in session / JWT claims
- [ ] Unique business keys scoped to `(tenant_id, company_id, code)`

---

## Phase 4 — Entity model rules

1. **Globally unique ID** — UUID v7 on every entity; never reuse IDs across tenants.
2. **Scope columns** — `tenantId` and/or `companyId` per `entity-schema.js`.
3. **Platform entities** — no tenantId (applications, modules, signups).
4. **Reference data** — currencies are global; FX rates may be tenant-overridable later.
5. **Journal lines** — child collection on `journal_entries`; separate table `gl_journal_line` in DB.

---

## Phase 5 — Prototype integration testing

To point the prototype at a running API:

```javascript
// In browser console or config override
WSApp.config.apiMode = "http";
WSApp.config.apiBaseUrl = "https://api.dev.example.com/api/v1";
```

`WSApiClient` will use REST instead of `localStorage`.

---

## Artefact index

| Artefact | Location |
|----------|----------|
| Architecture manifest | `js/core/architecture.js` |
| Entity schema registry | `js/platform/entity-schema.js` |
| API client abstraction | `js/platform/api-client.js` |
| Navigation (routes) | `js/navigation-data.js` |
| Module registry | `js/navigation/registry.js` |
| Seed / demo data | `js/data/store.js` |
| OpenAPI 3.1 | `docs/openapi/ws-api-v3.yaml` |

---

## Design system

- **Primary colours:** `#100220`, `#cc036a` (kit theme)
- **Fonts:** Inter (UI), Outfit (brand)
- **Module badge:** `.ws-module-badge` — retain in React for design-review builds

---

## Questions / gaps

Log implementation gaps against prototype screens showing:

> *Screen `{screen}` is registered for iterative design — add process logic in `modules/{module}.js`.*

These are intentional stubs for Stage 2+ process design.