Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
111 lines (95 loc) · 7.2 KB

ARCHITECTURE.md

File metadata and controls

111 lines (95 loc) · 7.2 KB

OpenFoundry Architecture

The canonical technical documentation lives in docs/. This file is a short top-level overview; for runtime detail follow the links below.

Stack at a glance

  • Backend: Go (single module rooted at github.com/openfoundry/openfoundry-go) with 41 service binaries under services/ and 32 shared packages under libs/.
  • Frontend: React 19 + Vite + TypeScript in apps/web/.
  • Contracts: Protobuf in proto/, Go code generated to libs/proto-gen/ via buf (run make gen).
  • SDKs: TypeScript / Python / Java in sdks/, generated from the proto + OpenAPI surface.
  • Storage: Postgres (CNPG + PgBouncer), Cassandra, Kafka (Strimzi
    • MM2), Iceberg (Lakekeeper), Vespa (search + RAG), Temporal (workflow), Ceph S3.
  • Infra: Helm + ArgoCD + Terraform under infra/.

For agent-facing onboarding (commands, gotchas, what NOT to read), see the root CLAUDE.md.

Service grouping

Services are grouped into Helm releases ("ownership boundaries") rather than physically merged crates. The current grouping:

                ┌─────────────────────────────┐
                │  apps/web (React 19 + Vite) │
                └──────────────┬──────────────┘
                               │
   ┌───────────────────┬───────┴───────────┬──────────────────────┬─────────────────────┐
   │  of-platform      │  of-data-engine   │  of-ontology         │  of-ml-aip          │
   │  edge-gateway     │  connector-mgmt   │  ontology-definition │  model-catalog      │
   │  identity-fed.    │  ingestion-repl   │  ontology-actions    │  model-deployment   │
   │  authorization    │  dataset-versioni │  ontology-query      │  agent-runtime      │
   │  tenancy-orgs     │  lineage          │  object-database     │  llm-catalog        │
   │                   │  media-sets       │  ontology-indexer*   │  retrieval-context  │
   │                   │  pipeline-build   │                      │  ai-evaluation      │
   │                   │  sql-bi-gateway   │                      │  ai-sink*           │
   └───────────────────┴───────────────────┴──────────────────────┴─────────────────────┘
                               │
                ┌──────────────┴──────────────────────────────────┐
                │  of-apps-ops                                    │
                │  application-composition  notebook-runtime      │
                │  ontology-exploratory     solution-design       │
                │  workflow-automation      notification-alerting │
                │  audit-compliance + audit-sink*                 │
                │  telemetry-governance                           │
                │  federation-product-exchange                    │
                │  code-repository-review   sdk-generation        │
                │  entity-resolution                              │
                └─────────────────────────────────────────────────┘
                               │
   ┌──────────┬───────────┬────┴─────┬─────────┬─────────┬───────────┬─────────────┐
   │ Cassandra│ Postgres  │  Kafka   │ Iceberg │ Vespa   │ Temporal  │ Ceph (S3)   │
   │          │ (CNPG +   │ (Strimzi │ (Lake-  │ (search │ (workflow │ (multisite) │
   │          │  PgBoun)  │  + MM2)  │  keeper)│  + RAG) │  engine)  │             │
   └──────────┴───────────┴──────────┴─────────┴─────────┴───────────┴─────────────┘

   * = Kafka sinks (counted separately from ownership boundaries).

The grouping is consolidation by ownership and Helm release, not a claim that the source tree has been physically merged. The ownership boundaries are defined in docs/architecture/adr/ADR-0030-service-consolidation-30-targets.md and the per-service status lives in docs/architecture/service-consolidation-map.md.

Recommended entry points

Cross-cutting invariants

These contracts are pinned by tests in libs/core-models/**/*_test.go and must not drift:

  • /healthz payload shape (status, service, version, timestamp).
  • JWT claims field names + JSON tags (libs/auth-middleware/claims.go).
  • Dataset RID format ri.foundry.main.dataset.<uuid-v7>.
  • Transaction state / type tokens (open|committed|aborted, snapshot|append|update|delete).
  • Marking source discriminator ({"kind": "direct"} / {"kind": "inherited_from_upstream", ...}).
  • Media reference camelCase keys (mediaSetRid, mediaItemRid, branch, schema).
  • Schema field type discriminator ({"type": "DECIMAL", "precision": ..., "scale": ...}).

Bounded contexts (deeper reading)

Domain Service / library README
Identity & federation services/identity-federation-service README
Authorization (Cedar/ABAC/RBAC) services/authorization-policy-service README
Datasets, branches, transactions services/dataset-versioning-service README
Media sets services/media-sets-service README
Ontology kernel (shared) libs/ontology-kernel CLAUDE.md
AI kernel (shared) libs/ai-kernel-go CLAUDE.md
Edge / proxy services/edge-gateway-service README
Audit pipeline libs/audit-trail, services/audit-sink README