Architecture Overview

Platform Summary

• LeafLock ships as a React SPA (frontend/) talking to a Go Fiber API (backend/).
• PostgreSQL 15+ stores encrypted content; Redis 7+ handles sessions, rate limits, and share state.
• Only the frontend is internet-facing—API and databases stay on the private network.

Tip

Use these guides whenever you need source file references or want to validate a deployment matches the canonical architecture.

Core Systems

Frontend

React 18 + Vite SPA under frontend/ manages note editing, client-side crypto, and collaboration UI.

Backend

Go Fiber API under backend/ exposes REST, WebSocket, rate limits, and background jobs.

Encryption

Client libsodium + server ChaCha20-Poly1305 enforce zero-knowledge storage for every note.

Database

PostgreSQL schema lives in backend/database/schema.go with encrypted columns throughout.

Runtime Flow

• Vite builds the SPA entry point at frontend/src/main.tsx; it loads per-user keys via cryptoService.
• Authenticated calls go through SecureAPI (JWT + CSRF token handling) to /api/v1/*.
• backend/server/app.go wires Fiber middleware (recover, logging, compression) before routes.go adds security controls.
• PostgreSQL queries run through pgx pools; Redis maintains session state, rate limit buckets, and share-link cache entries.
• Background services under backend/services/ seed the default admin, rotate encryption keys, and purge trashed notes daily.

frontend/src/         React UI & encryption helpers
backend/server/     Fiber bootstrap + health handlers
backend/routes.go   Middleware stack + REST routing
backend/services/   Background jobs & schedulers
backend/websocket/  Collaboration hub and message types

Deployment Footprint

• Default compose stack: frontend, backend, PostgreSQL, Redis (docker-compose.yml).
• Health: /api/v1/health/live (liveness) and /api/v1/health/ready (gated by server/ReadyState flags).
• Metrics: set ENABLE_METRICS=true to mount Prometheus middleware from backend/metrics/prometheus.go.