Architecture

All infrastructure lives in eu-west-1 (Ireland), AWS account 559401928829.

Request flow

Browser → CloudFront → S3          (React app — static files)
Browser → API Gateway → Lambda     (all REST endpoints)
Browser → Cognito                  (auth / JWT issuance)
Lambda  → DynamoDB                 (entity data)
Lambda  → S3                       (presigned document URLs)

AWS resources

Multi-tenancy

Tenant isolation is enforced at three independent layers:

• Cognito — users belong to a group named tenant-{id}. The tenantId is embedded in the JWT as custom:tenantId.
• Lambda — shared/auth.js extracts tenantId from the JWT on every request. No request can claim another tenant's ID.
• DynamoDB — every record has tenantId as its partition key. All queries are scoped to tenantId = :tid. Cross-tenant reads are structurally impossible.

Tenant roles

Database — single-table design

Table: supplier-platform-v2  ·  PK: tenantId  ·  SK: entityType#entityId

Security: Deletion protection ON  ·  PITR (point-in-time recovery) ON  ·  AES-256 encryption

Document storage

S3 path structure:

s3://supplier-platform-documents-559401928829/
  {tenantId}/{entityId}/{category}/{fileId}__{fileName}

Upload flow: Frontend calls Lambda to get a presigned PUT URL (5 min TTL) → browser uploads directly to S3 → Lambda never touches file bytes. Download links are presigned GET URLs with 1-hour TTL, generated at list time.

Modules

Feature documentation for each module in the platform.

Suppliers  Live

Routes: /suppliers, /suppliers/:id

Manage the company's supply chain. Each supplier record tracks contact info, category, relationship owner, goods supplied, and status.

Statuses

Documents

Five categories: Certifications, Contracts & Agreements, Quotes, Invoices, Other. Drag-and-drop upload directly to S3 via presigned URL.

Clients  Live

Routes: /clients, /clients/:id

Manage client relationships with a sales pipeline model. Notes are inline-editable (click to edit, ⌘↵ to save).

Pipeline

Documents

Three categories: Contracts & Agreements, Quotes, Invoices.

People (HR)  Live

Routes: /people, /people/:id

Employee records. Separate from platform users — an employee does not need a platform login. Optionally linked to a Cognito user via userId.

Key fields

firstName, lastName, fullName, jobTitle, department, employmentType, status, startDate, workEmail, personalEmail, phone, salary (annual GBP), managerId (links to another employee), userId (optional Cognito link), notes

Statuses

Documents

Four categories: Contracts, Right to Work, Qualifications, Other Docs.

Contacts  Live

Route: /contacts, /contacts/:id

A cross-entity contact book. Each contact record represents a named person or company and can be linked to any number of suppliers and/or clients. Contacts are created automatically when a supplier or client is added (using the entity name as the contact name and the "Contact details" field as free-text contact info), and can also be created manually from the Contacts page.

Key fields

name (required), contactDetails (free-text — email, phone, address, etc.), linkedSuppliers[] (supplier IDs), linkedClients[] (client IDs), isPrimary (boolean — marks the primary contact for a supplier or client), notes, sourceType (manual | supplier | client), sourceId

Primary contacts

Each supplier and client detail page shows a "Primary contact" section (the contact with isPrimary: true linked to that entity) and an "Additional contacts" section for all others. The primary contact can be changed from the supplier or client detail page — the change is applied optimistically in the UI and two PATCH calls are fired in sequence to promote the new primary and demote the old one.

Linking

Linked suppliers and clients are shown in the contact detail modal and are clickable — they navigate directly to the supplier or client detail page. Additional supplier and client links can be added inline from the contact modal using the link picker.

Assets  Live

Routes: /assets, /assets/:id

Track company assets such as laptops, desktops, phones, equipment, vehicles, and furniture. Each asset has a name, type (from a predefined dropdown), owner (selected from the People list), location, and a free-text asset tag for internal IDs or serial numbers.

Key fields

name (required), assetType (Laptop, Desktop, Monitor, Phone, Tablet, Printer, Networking, Server, Peripheral, Vehicle, Furniture, Tool, Other), assetOwner (free-text, searchable from People list), assetLocation (free-text), assetTag (free-text — serial number, barcode, etc.), status, notes

Statuses

Change history

Every asset has a full audit trail. The detail page shows a timeline of all changes — each entry records the action (created or updated), which fields changed, and the before/after values. History entries are stored as separate DynamoDB records using the ASSET_HISTORY#assetId#timestamp SK pattern and are written as best-effort side effects during create and update operations.

People integration

The People (Employee) detail page includes an "Assigned assets" card that shows all assets whose assetOwner matches the employee's full name. Clicking an asset navigates to the asset detail page.

Invoicing  Live

Routes: /invoices, /invoices/:id

Create and manage client invoices with automatic invoice numbering (INV-0001, INV-0002, …) and server-side PDF generation with company branding. Invoices are linked to clients and contain line items with descriptions, quantities, and unit prices.

Key fields

invoiceNumber (auto-generated), clientId, clientName, lineItems[] (each with description, quantity, unitPrice), subtotal (computed), tax (computed), total (computed), issueDate, dueDate, paymentTerms, notes, status

Statuses

PDF export

Each invoice can be exported as a branded PDF. The PDF is generated server-side by the generateInvoicePdf Lambda using pdfkit, and includes the company name, address, accent colour (from Company Settings), a line items table with alternating row colours, totals, and optional notes. The PDF is returned as a binary response and downloaded directly in the browser.

Settings  Live

Route: /settings (tenant admins only)

Team management

Company branding

The Workspace tab lets admins configure company branding used across the platform and on exported PDFs. Fields: companyName, companyAddress, companyPhone, companyEmail, companyWebsite, accentColor (hex colour picker, defaults to #4F46E5). Stored as a single DynamoDB record with SK COMPANY_SETTINGS#main.

Admin back-office  Live

Route: /admin (platform-admin group only)

Separate area with distinct dark sidebar. Inaccessible to tenant users. Manage all tenants — create, list, and permanently delete tenants with all their data.

API Reference

Base URL: https://ycn03ustd3.execute-api.eu-west-1.amazonaws.com
All endpoints require Authorization: Bearer <cognito-id-token>. The tenant is derived from the JWT.

Suppliers

Clients

Employees

Contacts

Assets

Invoices

Employee events (calendar)

Company settings

Team management

Admin (platform-admin only)

Document upload pattern

All upload-url endpoints accept the same request body:

{
  "fileName": "contract.pdf",
  "fileType": "application/pdf",
  "fileSize": 102400,
  "category": "contracts"
}

Returns a presigned S3 URL. The browser then PUTs the file directly to S3 — Lambda never handles file bytes. Download URLs in list responses are presigned GET URLs with a 1-hour TTL.

Lambda functions

All 55 Lambda functions. Runtime: nodejs22.x. All share a single deployment bundle at backend/functions.zip. Shared helpers live in backend/functions/shared/.

Deployment

How to build and deploy the frontend and backend.

Master deploy script

# Full deploy (backend + frontend)
./deploy-all.sh

# Frontend only (most common after UI changes)
./deploy-all.sh --frontend

# Specific Lambda functions only
./deploy-all.sh --lambdas "supplier-platform-createInvoice supplier-platform-updateInvoice"

# Skip npm bundle rebuild (re-use existing zip)
./deploy-all.sh --backend --skip-build

# Dry run — prints plan without making changes
./deploy-all.sh --dry-run

All Lambda code lives in one zip (backend/functions.zip). Every Lambda points into the same zip via its handler path (e.g. backend/functions/createEmployee.handler).

Frontend deploy

Builds with Vite → syncs hashed assets to S3 with Cache-Control: immutable → syncs index.html with no-cache → invalidates CloudFront /*.

Backend deploy

Bundles all backend/functions/ into a single zip, then for each Lambda: updates code → waits → updates runtime to nodejs22.x → waits. Takes ~10 minutes. The waits are necessary — Lambda blocks config changes while a code update propagates.

CI/CD (GitLab)

Pushes to main trigger the GitLab CI pipeline defined in .gitlab-ci.yml. The pipeline runs security scanning (SAST + Secret Detection) on every push and merge request, then builds the frontend and deploys both the frontend (S3 + CloudFront) and backend (Lambda) on main branch only.

Adding a new Lambda

1. Write the handler in backend/functions/yourFunction.js
2. Add the function name to DEFAULT_FUNCTIONS in deploy-all.sh
3. Copy an existing setup script (e.g. setup-clients-api.sh) and adapt it
4. Run the setup script once to create the Lambda and API Gateway route
5. Future deploys via deploy-all.sh or GitLab CI will keep it updated

Environment variables

Frontend (.env)

Lambda env vars (per function)

Updating these docs

Edit docs/index.html in the repo and push to main. Cloudflare Pages (connected to GitLab) rebuilds within ~30 seconds — no build step required.

Decision Log

Key architectural decisions, why we made them, and the trade-offs involved.

Single-table DynamoDB design

All entity types live in one table: tenantId (PK) + entityType#entityId (SK).

Why: DynamoDB performs best with access patterns baked into the key structure. One table means one IAM policy, one set of backups, one billing unit. Adding a new entity type is zero-infrastructure — just a new SK prefix.

Trade-offs: Harder to reason about for newcomers. sk is a DynamoDB reserved word — requires ExpressionAttributeNames: { '#sk': 'sk' } in all expressions.

Serverless compute (Lambda only)

Why: Zero infrastructure management. Pay-per-request — effectively free for the first 1M requests/month. Cold starts (~200ms) acceptable for B2B use.

Trade-offs: All functions share one bundle — a bad require() breaks everything. 15-minute execution limit (not a current constraint).

Cognito for auth

Why: Native AWS integration, free up to 10,000 MAU, handles email verification and password reset. Groups map cleanly to tenant roles.

Trade-offs: Single-region only — no native multi-region HA. JWT validation is trust-based (claims read without signature verification) — sufficient for internal use.

Presigned S3 URLs for document upload

Why: Browser uploads directly to S3. Lambda never handles file bytes — no 6MB payload limit, no base64 overhead, no bandwidth costs through Lambda.

Trade-offs: Two round trips instead of one. Download links expire after 1 hour.

Bash scripts instead of Terraform/CDK

Why: Speed of iteration — a new Lambda + route is ~20 lines of bash. No state file drift. Fully transparent.

Trade-offs: Setup scripts are not idempotent. No drift detection.

Mitigation: Named setup-*.sh (run once) vs deploy.sh (idempotent, run every deploy).

eu-west-1 (Ireland) as primary region

Why: Closest AWS region to UK/Europe. GDPR-compliant EU data residency. Full service availability.

Future HA region: eu-central-1 (Frankfurt) — nearest alternative EU region with full service parity.