Architecture Overview

OPS Platform v2 is a modular full-stack platform built around a Next.js webapp, a FastAPI core API, Supabase/PostgreSQL, Redis, SSO/OIDC auth, and operational deployment workflows.

Browser
  |
  |-- Next.js webapp: apps/webapp
          |
          |-- same-origin auth/API routes
          |-- server/client API client
          v
      FastAPI Core API: backend/core-api
          |
          |-- Supabase/Postgres
          |-- Redis
          |-- OIDC/JWKS/UserInfo
          |-- integrations/webhooks
          |-- escrow/web3 providers
          |-- observability/metrics

Primary runtime components

Component	Responsibility
apps/webapp	Next.js UI, auth routes, modules, dashboards, API proxy helpers
backend/core-api	FastAPI API, RBAC, auth, platform modules, external API, metrics
Supabase/PostgreSQL	v2 schema, profiles, roles, tasks, payments, escrow, notifications, integrations
Redis	notifications/SSE and short-lived operational state
app-doc	Docusaurus documentation site
monitoring	Prometheus/Grafana/Alertmanager configs
.github/workflows	CI, deployment, security checks

v2 architectural direction

AGENTS.md is the canonical agent/developer guide:

• Backend modules belong under backend/core-api/app/modules.
• Frontend feature modules belong under apps/webapp/src/modules.
• Legacy adapters belong under backend/core-api/app/api/v1/legacy.
• New frontend code should prefer module APIs over direct route-level fetch logic.
• Query filtering/aggregation should happen in the database where practical.