Architecture
System Architecture
Overview of the Burning Ash Protocol system architecture — components, data flow, and design principles.
System Architecture
This document provides a high-level overview of the BAP system architecture.
Overview
BAP is a client-server application with:
- Go Backend — REST API with Chi router
- Next.js Frontend — React-based web application
- SQLite/PostgreSQL — Database
- External Providers — Storage and notification services
Architecture Diagram
┌─────────────────────────────────────────────────────────────────────────┐
│ CLIENT │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Host Dashboard │ │ Survivor Portal │ │
│ │ (Next.js Web Application) │ │ (Next.js Web Application) │ │
│ └──────────────┬───────────────┘ └──────────────┬──────────────┘ │
└─────────────────┼─────────────────────────────────────┼──────────────────┘
│ HTTPS (TLS 1.3) │ HTTPS
▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API SERVER │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Chi Router │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Host │ │ Survivor │ │ Will │ │ │
│ │ │ Handlers │ │ Handlers │ │ Handlers │ │ Handler │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └─────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────┼─────────────────────────────────┐ │
│ │ MIDDLEWARE │ │ │
│ │ ┌─────────────┐ ┌────────────┐ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Auth │ │ Rate │ │ │ CORS │ │ Security │ │ │
│ │ │ JWT │ │ Limiter │ │ │ │ │ Headers │ │ │
│ │ └─────────────┘ └────────────┘ │ └────────────┘ └────────────┘ │ │
│ └─────────────────────────────────┴─────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────┼─────────────────────────────────┐ │
│ │ SERVICES │ │ │
│ │ ┌─────────────┐ ┌────────────┐ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Crypto │ │ Scheduler │ │ │Connector │ │ Storage │ │ │
│ │ │ (AES/SSS) │ │ (Cron) │ │ │ Manager │ │ Manager │ │ │
│ │ └─────────────┘ └────────────┘ │ └────────────┘ └────────────┘ │ │
│ └─────────────────────────────────┴─────────────────────────────────┘ │
│ │ │
└────────────────────────────────────┼────────────────────────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────────┐
│ DATABASE │ │ STORAGE │ │ EXTERNAL SERVICES │
│ (SQLite/PG) │ │ (S3/GDrive/ │ │ (SMTP/Twilio/ │
│ │ │ Dropbox/SFTP) │ │ WhatsApp/Telegram) │
│ ┌─────────────┐ │ │ │ │ │
│ │ hosts │ │ │ ┌─────────────┐ │ │ │
│ │ survivors │ │ │ │ Encrypted │ │ │ │
│ │ wills │ │ │ │ Documents │ │ │ │
│ │ connectors│ │ │ │ (.enc) │ │ │ │
│ │ storages │ │ │ └─────────────┘ │ │ │
│ │ liveness │ │ └───────────────────┘ └───────────────────────┘
│ │ transfers │ │
│ │ audit_log │ │
│ └─────────────┘ │
└───────────────────┘Components
Frontend (Next.js)
- Framework: Next.js 16 with React 19
- Language: TypeScript 5.9
- Styling: Tailwind CSS 4 with shadcn/ui
- Features:
- Host Dashboard for will management
- Survivor Portal for authentication and access
- Admin Panel for platform management
- Responsive glassmorphism UI with dark/light mode
- Pricing page with Stripe integration (SaaS mode)
Backend (Go)
- Framework: Go 1.26, Chi v5 router
- Database: SQLite (dev) / PostgreSQL (prod)
- ORM: GORM
- Encryption: AES-256-GCM, Shamir's Secret Sharing, Ed25519 signing
Database
- SQLite: Development/default
- PostgreSQL: Production recommended
- Tables: hosts, survivors, wills, connectors, storages, liveness_checks, transfers, audit_log
External Services
- Storage: Google Drive, Dropbox, AWS S3, SFTP
- Notifications: Email (SMTP), SMS (Twilio), WhatsApp (Meta Cloud API), Telegram (Bot API)
- Billing: Stripe (SaaS mode only)
Data Flow
1. Will Creation Flow
Host → Upload Documents → Encrypt (AES-256-GCM)
→ Generate DEK → Split via SSS
→ Encrypt shares → Upload to Storage
→ Store metadata → Will Active2. Liveness Check Flow
Scheduler → Check Due → Send Notification
→ Wait Response → Confirmed?
→ Yes: Schedule Next → No: Increment Retry → Retry < Limit?
→ No (limit reached): Trigger Transfer3. Will Transfer Flow
Trigger → Notify All Survivors → Portal Opens
→ Each Survivor Verifies (OTP) → Collect SSS Shares
→ Threshold Met? → Reconstruct DEK
→ Decrypt Documents → Access GrantedSecurity Architecture
Encryption Layers
- TLS 1.3 — Data in transit
- AES-256-GCM — Document encryption
- Envelope Encryption — DEK encrypted by KEK
- SSS — DEK split across survivors
Authentication
- JWT tokens for host authentication
- OTP for survivor verification
- Backup codes as fallback
Rate Limiting
- Configurable per-endpoint limits
- Prevents brute force attacks
- Protects against abuse
Deployment Options
Development
- SQLite database
- Local storage
- Docker Compose
Production
- PostgreSQL database
- Cloud storage (S3/GDrive/Dropbox)
- Docker Compose or Kubernetes
- Reverse proxy (Nginx/Caddy)
Technology Stack
| Component | Technology |
|---|---|
| Backend | Go 1.26 |
| Router | Chi v5 |
| Database | SQLite (dev), PostgreSQL (prod) |
| ORM | GORM |
| Frontend | Next.js 16, React 19, TypeScript 5.9 |
| Styling | Tailwind CSS 4, shadcn/ui |
| Encryption | AES-256-GCM |
| Signing | Ed25519 (optional) |
| SSS | hashicorp/vault/shamir |
| Scheduler | Polling-based (30s interval goroutine) |
| SMTP (user-configured) | |
| SMS | Twilio |
| Meta Cloud API | |
| Telegram | Bot API |
| Storage | Google Drive, Dropbox, S3, SFTP |
| Billing | Stripe (SaaS mode) |
| Docs | Fumadocs (MDX) |
Design Principles
- Encrypt-first — Never store plaintext externally
- Zero-knowledge — Server never sees unencrypted documents
- Defense in depth — Multiple security layers
- Simplicity — Easy for non-technical survivors
- Resilience — Fallback connectors, graceful degradation
Next Steps
- Backend Architecture — Go backend details
- Frontend Architecture — Next.js frontend
- Database Schema — Schema design
- Connector System — Notification architecture