Architecture | Nebula Docs

NEBULA-ARCHITECTURE(1)

Nebula Manual

NAMEarchitecture — How Nebula separates source-control storage, policy, projections, and retrieval.

SOURCEnebula/docs/architecture.md

STATUSpre-alpha · protocol in design

Storage split

Three distinct storage layers with independent failure domains.

output

Metadata (Postgres)
  repos, refs, snapshots, entries
  workspaces, changesets, proposals
  merge intents, release gates
  policies, environments, integrations

Blob Store (S3-compatible)
  source bytes
  binary files
  encrypted private blobs
  projection bundles
  build artifacts

Vector DB (future)
  path/hash index today
  semantic embeddings tomorrow

Protocol vs product

Nebula owns the protocol, storage, and source-control primitives. Product experiences (auth, collaboration, billing) belong to integrators.

→Nebula: protocol resources and storage
→Registry: HTTP surface for protocol operations
→Auth: Integration concern (Better Auth, Auth0, etc.)
→Collaboration: Integration concern (proposals, reviews, comments)

Production requirements

Production deployments need durable metadata, object storage, auth enforcement, and operational readiness.

output

DATABASE_URL=postgres://...     # Postgres with schema migrations
BLOB_STORE_URL=s3://...       # S3-compatible object storage
NEBULA_AUTH_REQUIRED=true     # Enforce authentication
NEBULA_AUTH_PROVIDER=better-auth-rs
NEBULA_AUTH_SECRET=<32+ bytes>

Registry safety

Never expose a registry server publicly without authentication and durable storage configured.

Operational readiness

Validate production readiness before deployment.

output

NEBULA_TEST_PROFILE=fast ./tests/production/validate-production.sh