Contract summary

PRODUCT-CONTRACT.md at the workspace root fixes every name the seven surfaces must agree on. Names change there first, then in code. This page condenses it for orientation; the contract wins wherever they differ.

Taxonomy

• Brand: Trovensa only. Descriptor “Agentic intelligence for drug development.” Tagline “From evidence to progress.” Bare product names inside the app and the docs; the marketing prefix belongs to the site and the deck.
• Products, in order and all designed: evidence Evidence, plans Plans, review Review, progress Progress. Icons source, modules, review, program. Entry routes /evidence/questions, /plans/plans, /review/findings, /progress/overview.
• Pillars: CONTEXT (evidence), CONTINUITY (plans, progress), RECORD (review). Stages: discovery, preclinical, clinical, manufacturing.
• Status vocabulary: available, preview, designed, planned, roadmap. Mock data carries illustrative = true and an “Illustrative” label. Agent output is “agent-generated” or “proposed”.

Tenancy and identity

• Organization -> Program; scope kinds org and program; every scoped record carries organization_id, program_id, stage_id. New organisations get program default; the seed adds trv-101.
• Permission catalog: 72 strings (org 13, program 13, evidence 13, plans 14, review 10, progress 9) pinned in api/app/auth/permissions.py, mirrored in web/lib/auth/permissions.ts and the permissions page; compared by web/scripts/check-permissions-sync.mjs.
• Personas: 10 (org_owner, org_admin, org_member, org_auditor, program_owner, program_lead, scientist, quality_reviewer, manufacturing_specialist, viewer), version 1, seeded by migration 0001 and re-seeded at API start-up.
• Identity: bearer JWT. Production RS256 from the identity provider with pinned issuer and audience; development and tests HS256 with kid: dev, accepted only when APP_ENV is dev or test. Web: MSAL when NEXT_PUBLIC_AUTH_CLIENT_ID is set, otherwise NEXT_PUBLIC_DEV_TOKEN; bridge route /auth/bridge.

API

• Prefix /api/v1; program routes /programs/{program_id}/...; org routes /orgs/current/.... Router order: health, me, permissions, personas, providers, orgs, programs, connections, agent_runs, evidence, plans, review, progress, legacy.
• Route count: 117 designed (recounted with make routes-check; api/scripts/designed-routes.json). Migration 0001 creates 32 tables.
• Errors: RFC 7807 problem+json with request_id; ERROR_TYPE_BASE = https://console.trovensa.com/errors; 403 carries permission. Enums are text plus a named CHECK; alembic check stays clean.
• Settings fields: app_env, log_level, database_url, cors_origins, permissions_cache_ttl_seconds, public_api_base_url, auth_issuer, auth_audience, auth_jwks_url, dev_token_secret, secrets_prefix, worker_concurrency, sync_poll_seconds, agent_runtime_url, agent_runtime_arn, agent_model_id, feature_agent_runs.

DTO families

Every *Out carries id, created_at, updated_at; each family has the matching *Create and *Update where the route exists. The as-built deltas add id, timestamps and organization_id to UserOut and AgentEventOut, and ToolInvocationCreate accepts input only.

Web

Route tree /, /sign-in, /auth/bridge, /api/health, /p/[slug]/home, the four product trees, /p/[slug]/setup/{overview,connections,members,roles,agent-runs,audit} and /org/{settings,programs,users,groups,roles,audit}. Redirects 308: /p/<slug> to /p/<slug>/home, /org to /org/settings. Cookies last_program and shell_panel; theme key theme. Hooks useProgram().can(perm) and useHasOrgPermission(perm); no role checks.

Hosts, ports and ownership

Frozen after phase 0: the contract, forge.config.json, shared/**, api/app/auth/{permissions,personas}.py, web/lib/{content,routes}.ts, web/lib/auth/permissions.ts, web/lib/api/{types,endpoints}.ts, the three token files, site/lib/content.ts, web/scripts/check-permissions-sync.mjs. Writers: api-core, api-products, web-shell, web-products, site, docs (everything in docs/ except app/globals.css), agent, deck, infra. Section 9 records the as-built deltas after each integration step.

Source: PRODUCT-CONTRACT.md, forge.config.json, api/app/auth/permissions.py, api/app/auth/personas.py, api/app/main.py, api/app/config.py, api/scripts/designed-routes.json, web/lib/routes.ts