Development
BitVault is a Go monorepo (ADR-0002) with a Next.js web app and optional React
Native mobile client. The single binary bitvaultd runs all modules in v1;
the same source tree can be deployed as extracted services in later phases.
Quick Start
Prerequisites:
| Tool | Version | Purpose |
|---|---|---|
| Go | 1.22+ | All backend code |
| pnpm | 9+ | Web app and JS tooling |
| Docker + Docker Compose | Latest stable | Local dependency stack |
| task | 3+ | Build/test/run runner (Taskfile.yml) |
| buf | 1.30+ | Protobuf toolchain (lint + codegen) |
# Minimal: Postgres + MinIO + bitvaultd
task up:lite
# Full stack (adds Redis, NATS, OpenSearch)
task up:full
# Run tests
task test
# Regenerate proto-derived code after .proto changes
task gen
Contents
| Page | What it covers |
|---|---|
| Repository Structure | Monorepo layout, bounded-context conventions, import rules |
| Local Development | Dependency tiers, commands, running services locally |
| Contributing | ADRs, PR conventions, adding modules and storage providers |
Design Constraints for Contributors
- Cross-context imports are forbidden.
internal/filescannot importinternal/syncinternals. Contexts talk through gRPC APIs or events only. - Contracts are in
proto/. Never editgen/manually. - OTel from the first line. New services start with
platform/observabilitywiring before any domain logic. - Database changes are forward-only migrations. No rollback scripts; use expand/contract for safe schema evolution.