Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
57 lines (45 loc) · 3.25 KB

DEVELOPMENT.md

File metadata and controls

57 lines (45 loc) · 3.25 KB
Raw

Developer guide

Everything a contributor (or an AI coding agent) needs to work on OpenGP. Read this before your first change; link out to the detailed docs rather than duplicating them.

What this is

OpenGP — a multi-tenant, white-labeled private-equity intelligence platform: data room, portfolio analytics, cited AI chat (RAG), transaction reports, meeting transcription, Model Builder, and news/outreach. The UI is branded per workspace — never hardcode a customer name; UI copy uses the active workspace name or "the platform". @opengp/* is the npm scope; opengp is the default AWS resource-name prefix.

The shipping product is the web app (apps/web + apps/server).

Monorepo layout

  • apps/web — Next.js 15 frontend (App Router, standalone output)
  • apps/server — Express backend (Node 22+): auth, RLS-scoped data API, RAG ingest, background pollers
  • packages/core — shared pure logic (@opengp/core)
  • packages/backend-core — server-side AWS integrations: BDA parsing, Bedrock embed/rerank, AgentCore (@opengp/backend-core)
  • infra/terraform — the full AWS stack as code (see its README)
  • infra/ec2 — docker-compose + cloud-init for the app box
  • supabase/migrations — canonical schema history (applied manually via psql; the name is historical)
  • docs/ — architecture, deployment, security, and operations runbooks

How production runs (AWS)

Two EC2 boxes — an always-on app server (Caddy + frontend + backend via docker-compose at /opt/opengp) and a wake-on-demand meeting-bot box — plus Aurora Postgres (Serverless v2, RLS + pgvector), Cognito (auth), S3 (private docs bucket, public branding bucket), KMS, and Bedrock (RAG parse/embed/rerank + Model Builder sandbox). Full setup: docs/aws-migration/AWS-SETUP.md; deploys are manual — see docs/DEPLOYMENT.md.

Gotchas that pass local tests but break prod

  • All request-scoped DB access via reqScopedDb/withReqDb/asDb(req) (RLS as the caller); never an ad-hoc client, never a captured request JWT in a background job.
  • Never presign a stored/client-supplied S3 key → reconstruct the key server-side (cross-tenant hole otherwise).
  • RLS writes must be owner-scoped with symmetric WITH CHECK (a viewer could otherwise self-escalate).
  • Backend needs Node 22+. Run npm run build -w @opengp/core (and -w @opengp/backend-core) if core-dependent builds/tests fail.
  • Frontend NEXT_PUBLIC_* values are baked at build time — each var must be an ARG+ENV in Dockerfile.web, and changes need an image rebuild, not a redeploy.
  • Product-info pages (/changelog Architecture + Security): keep AI/model vendors generic ("Embedding module", not "Bedrock/Cohere"); security.ts must stay free of deployment identifiers (a test enforces it). Infra vendors (AWS, Cloudflare, Caddy) MAY be named.

Before a push

npm test (all workspaces green) + npm run typecheck clean in touched packages + the pre-deploy checklist in docs/DEPLOYMENT.md. CI runs build-test, dependency-audit, secret-scan, sast, and the browser-db gate on every PR — all five must be green before merge (scripts/gh-safe-merge.sh enforces this locally).