# BitVault

Kubernetes-native file storage, synchronization, sharing, and asset-management platform — architecture documentation.

Start here

The single most important document is the critique — read it first:

Critique & Risks →

The three load-bearing conclusions:

  1. Cut the web-CMS; make sync correctness the headline.
  2. Start as a modular monolith; reach microservices by extraction.
  3. Tier the infrastructure. Postgres + object store is the core; Redis, NATS, and OpenSearch are opt-in.

Architecture

System Overview

C4 context & container diagrams, the three planes, canonical flows

Bounded Contexts

Domain decomposition & context map with upstream/downstream relationships

Service Boundaries

Data ownership, the three planes, extraction triggers per service

High-Level Architecture

C4 views, canonical flows, deployment topology

Data Model

ERD, key invariants, storage strategy per layer

Architecture Decisions

37 ADRs — every major choice with consequences & alternatives

Deep dives

Sync Engine

Three-tree reconciliation, planner, cursor protocol, conflict resolution — 12 docs

Storage Subsystem

Content-addressing, chunking, dedup, multipart uploads, versioning, GC — 12 docs

Platform Engineering

Containers, K8s, Helm, GitOps, CI/CD, IaC, DR, backups — 12 docs

Security Review

Threat model, authN/Z, tenant isolation, encryption, compliance — 13 docs

Product Strategy

30+ features scored: WASM plugins, Functions, Cedar policy, E2E vaults, S3 API

Services

Per-service detail: Gateway, Identity, Files, Storage, Sync, Sharing, Search, Billing

How to read, by audience

You are… Read, in order
Evaluating the engineering critique → contexts → services → architecture → roadmap → ADRs
Deciding whether to build it goals → critique → roadmap
Going to implement it requirements → architecture → repo structure → data model → ADRs
Going to operate it deployment topology → packaging ADR

Conventions