Certivo Development Assistant

Expert guidance for working with the Certivo AI-powered compliance platform codebase.

What This Skill Does

Provides comprehensive development assistance for Certivo, a modular monolith that manages Bill of Materials (BOM), supplier certificates, compliance status tracking, risk assessment, and AI-powered document parsing through CORA (Compliance Operations & Risk Assistant).

Architecture Philosophy

Ship as a modular monolith with strict module boundaries and dependency injection. Each module has explicit interfaces serving as future "extraction seams" for microservices if needed.

Critical Instructions

1. **ALWAYS reference Architecture.md when making decisions**

2. **Follow the layered dependency flow**: Controller → Service → Repository → Database

3. **Respect module boundaries** - modules communicate through explicit interfaces only

4. **Use tenant context** - all database queries automatically scope via AsyncLocalStorage

5. **No partial implementations** - complete features fully before moving on

6. **No code duplication** - check existing codebase and reuse functions

7. **No dead code** - delete unused code completely

8. **Simple over complex** - prefer simple functions over abstractions

9. **Testing with real services** - use actual database/Redis, no mocks

10. **Comprehensive tests** - tests must be verbose and reveal real flaws

Quick Start Commands

Initial Setup

```bash

1. Start infrastructure (Postgres + Redis)

cd infra/docker && docker compose up -d && cd ../..

2. Set up database

pnpm db:migrate

pnpm db:seed

3. Generate JWT token

node infra/docker/generate-dev-token.mjs

4. Configure environment

cp .dev.env.example .dev.env

Edit .dev.env: set CERTIVO_API_TOKEN and CORA_OPENAI_API_KEY

5. Start all services

pnpm dev

```

Services available at:

Repository Structure

```

/apps → Deployable applications (api, web, worker, cora)

/api → Express REST API server (port 4000)

/web → Next.js dashboard/UI (port 3000)

/worker → Temporal workflow worker

/cora → Python FastAPI sidecar for LLM operations (port 8082)

/modules → Domain modules (compliance, supplier, dashboard, etc.)

/libs → Cross-cutting libraries (auth, db, logging, tracing)

/infra → Infrastructure (Docker, Terraform, DB migrations)

/docs → Architecture decisions and operations guides

/data → Sample fixtures and payloads

/scripts → Development and smoke test scripts

```

Module Organization Pattern

Every domain module follows this structure:

```

modules/{module-name}/

src/

controllers/ # HTTP handler adapters (thin, validation only)

services/ # Business logic and orchestration

repositories/ # Data access layer (raw SQL with tenant context)

dtos/ # Request/response types (Zod schemas)

validation/ # Input validation schemas

errors.ts # Module-specific exceptions

index.ts # Public exports (module interface)

```

Technology Stack

Backend

CORA AI (Python Sidecar)

Frontend

Validation & Auth

Multi-Tenancy & Security

Tenant Context Model

Authentication Flow

1. Middleware validates JWT using JWKS or HS256

2. Extracts claims: `tenant_id`, `roles`, `email`

3. Sets AsyncLocalStorage context for tenant scoping

4. RLS policies enforce tenant isolation at database level

Database

Migration System

Key Migrations

1. **001_core_schema.sql**: Core tables (tenants, users, products, boms, components, suppliers, certificates)

2. **002_views_and_functions.sql**: Materialized views, helper functions

3. **003_rls_policies.sql**: Row-level security policies

4. **004_document_lifecycle.sql**: Document lifecycle management

5. **005_search_rag.sql**: pgvector extension, embeddings tables

Important Tables

Core Modules

Request Flow Pattern

1. **Middleware Stack** (in order):

- JSON parsing (10MB limit)

- Request context (correlation ID)

- API version header

- Prometheus metrics

- Request logging

- JWT auth verification

- Tenant context injection

2. **Controller Layer**:

- Validate request body via Zod schema

- Extract tenant context

- Call service method

- Transform to DTO

- Return response

3. **Service Layer**:

- Business logic and orchestration

- Inter-module coordination

- Error handling

- Audit logging

4. **Repository Layer**:

- Raw SQL queries with tenant context

- Transaction management

- Data transformation

Compliance Status Engine Logic

```

if (no certificate) return "MISSING"

else if (now() > valid_until) return "EXPIRED"

else if (any finding.concentration_ppm > regulation_limit_ppm) return "OVER_LIMIT"

else return "COMPLIANT"

```

Unit Normalization

Smoke Tests

```bash

Test BOM upload, cert ingestion, and CORA AI endpoints

pnpm lab:test

Test risk/impact prediction and regulation limit simulation

pnpm risk:test

```

Common Development Commands

```bash

Start all services (recommended)

pnpm dev

Build all packages

pnpm build

Lint all packages

pnpm lint

Build a single module

pnpm --filter @certivo/{module-name} build

Run module in dev mode

pnpm --filter @certivo/{module-name} dev

Database migrations

pnpm db:migrate

Seed sample data

pnpm db:seed

```

Environment Variables (Required)

Development (.dev.env)

```bash

DATABASE_URL="postgres://certivo:certivo@localhost:5432/certivo"

AUTH_JWT_SECRET="dev-secret"

AUTH_ISSUER="https://auth.dev.certivo"

AUTH_AUDIENCE="certivo-api"

CORA_OPENAI_API_KEY="sk-xxxx" # REQUIRED

CERTIVO_API_TOKEN="<from generator>" # REQUIRED

CORA_API_URL="http://localhost:8082"

TEMPORAL_ADDRESS="localhost:7233"

```

Logging Patterns

Key API Endpoints

Production Deployment

See `docs/DEPLOYMENT.md` for full guide.

Quick production deployment:

```bash

cp .env.production.example .env.production

Edit .env.production with production values

node infra/docker/generate-dev-token.mjs

./scripts/deploy.sh up

```

Constraints