Expert guidance for the Certivo AI compliance platform - a modular monolith managing BOMs, supplier certificates, compliance tracking, and AI-powered document parsing through CORA.
Expert guidance for working with the Certivo AI-powered compliance platform codebase.
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).
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.
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
```bash
cd infra/docker && docker compose up -d && cd ../..
pnpm db:migrate
pnpm db:seed
node infra/docker/generate-dev-token.mjs
cp .dev.env.example .dev.env
pnpm dev
```
Services available at:
```
/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
```
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)
```
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
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
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
```
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"
```
```bash
pnpm lab:test
pnpm risk:test
```
```bash
pnpm dev
pnpm build
pnpm lint
pnpm --filter @certivo/{module-name} build
pnpm --filter @certivo/{module-name} dev
pnpm db:migrate
pnpm db:seed
```
```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"
```
See `docs/DEPLOYMENT.md` for full guide.
Quick production deployment:
```bash
cp .env.production.example .env.production
node infra/docker/generate-dev-token.mjs
./scripts/deploy.sh up
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/certivo-development-assistant/raw