Internal Test Suite

The RICA Atlas test surface is part of platform discipline. It gives technical and diligence readers a view into how database integrity, financial logic, workflow behavior, background jobs, API policy, metrics verification, and browser-level product behavior are protected as the platform evolves.

The suite does not yet represent a complete end-to-end certification matrix. It does provide meaningful coverage across the systems that matter most to project, loan, note, reporting, and workflow coherence.

Test Philosophy

Atlas uses layered confidence. Typechecking protects interface consistency. API and service tests protect core behavior. Scenario and seed tests protect generated-world assumptions. Worker tests protect background processing. Browser tests protect complex user-facing workflows.

This matters because Atlas is not a static website. It is the operating layer for a market. Changes to project records, loan modeling, metric verification, permissions, or note waterfalls can affect investor-facing views.

Canonical Commands

npm run typecheck
npm run build
npm run test:demo-seed --workspace apps/api
npm run test --workspace apps/api
npm run test:web:metrics-panel

Additional environment and data setup commands:

npm run db:migrate --workspace apps/api
npm run db:seed:scenario --workspace apps/api -- --apply --json

Coverage Matrix

Surface	Current Confidence Mechanism
Database schema and migrations	SQL definitions, migration scripts, migration status checks, and route or service tests that exercise real query paths.
Generated scenarios	Demo-seed validation for chronology, economics, cash-flow timelines, inventory, and schema consistency.
Worker behavior	Job queue, reporting jobs, document scans, and reconciliation tests inside the API suite.
API routes	Route tests across notes, portfolios, project financials, project loans, metrics, access, and list scoping.
Financial modeling	Service tests for project waterfalls, loan modeling, servicing, note waterfalls, and distribution ledger allocation.
Metrics workflow	Tests for metric assignments, submissions, review queues, approval flows, dashboards, and KPI fallbacks.
Web behavior	Browser-oriented metrics panel coverage through `npm run test:web:metrics-panel`.

Database Confidence

Atlas does not currently have a single test:db script. Database confidence is distributed across schema files, migration scripts, seed generation, and tests that exercise the data model through real application behavior.

The most important database-focused command today is:

npm run test:demo-seed --workspace apps/api

That suite covers generated world structure, chronology, economics, cash-flow timelines, inventory, and schema consistency.

Worker And Job Processing

Worker behavior is covered inside the main API suite. Representative files include:

apps/api/src/services/job-queue.test.ts
apps/api/src/services/report-jobs.test.ts
apps/api/src/services/document-scans.test.ts

These tests validate queued-job processing, export and reporting job generation, automated document scan gating, and worker-triggered operational transitions that affect access or reporting.

API And Service Coverage

The broadest behavioral coverage sits under apps/api/src/. Representative route and service tests cover note cash-flow derivation, note loan purchases, note waterfall recalculation, notes watchlist workflow, portfolio scenarios, project financials, project list scoping, project loan proposals, project loans, and project metrics workflow.

Service coverage includes desk access and auth behavior, FX rate handling, project and note access policies, project waterfall and loan modeling, project loan servicing, note waterfall modeling, note distribution ledger allocation, reporting generation, and project reporting calculations.

Web And Browser Coverage

The web layer currently has one explicit browser-oriented entry point:

apps/web/components/projects/viewer-panels/project-metrics-panel.browser.test.tsx

It runs through:

npm run test:web:metrics-panel

This test focuses on a complex metrics workflow surface: dashboard rendering, metric-set management, partial submission controls, audit queues, platform approval queues, and KPI-only fallback behavior.

Recommended Regression Sequence

For most platform changes, use this sequence:

Run npm run typecheck.
Run npm run test --workspace apps/api for server-side behavior.
Run npm run test:demo-seed --workspace apps/api when seeded-world assumptions may change.
Run npm run test:web:metrics-panel when shared metrics UX or browser rendering is at risk.
Run npm run build before release-oriented handoff.

Coverage Priorities

Coverage priorities include API contract testing, open project account records, GIS and asset-boundary data, permissioned visibility, audit trails, document access, material-event logs, rate-limit and integration behavior, responsive rendering, accessibility, performance budgets, large file uploads, worker throughput, and release gates.

These areas matter because they map directly to investor confidence: the platform proves that asset records are accurate, permissions are enforced, workflows are traceable, and market-critical calculations remain stable.