GitCaddy/GitCaddy Vault
Limited
2
0
Fork 0
Code Issues Releases 9

docs: Add architecture documentation for vault-server sync

Browse Source 
Explains that vault is source of truth for templates/locales,
and server syncs from vault at build time via sync-vault.sh.
Documents why Go plugins aren't used (compilation requirements).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
David H. Friedel Jr.
2026-01-18 17:11:06 -05:00
parent 11d57c9f37
commit 9cfa9ebc82
1 changed files with 44 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@@ -241,6 +241,50 @@ GitCaddy Vault uses the following tables:
## Development
### Architecture: Vault ↔ Server Sync
**Important for contributors and AI assistants:**
GitCaddy Vault is the **source of truth** for vault-related templates and locales. Due to Go plugin compilation limitations, vault code is compiled directly into GitCaddy Server rather than loaded as a dynamic plugin.
```
┌─────────────────────────────────────────────────────────────────┐
│ gitcaddy-vault (this repo) │
│ SOURCE OF TRUTH for: │
│ • templates/repo/vault/*.tmpl → UI templates │
│ • locale/*.json → Translation strings │
│ • models/, services/, crypto/ → Business logic │
│ • license/ → License validation │
└─────────────────────────┬───────────────────────────────────────┘
│
BUILD TIME SYNC
(scripts/sync-vault.sh)
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ gitcaddy-server │
│ RECEIVES from vault: │
│ • templates/repo/vault/*.tmpl ← Copied from vault │
│ • options/locale/*.json ← vault.* keys merged │
│ │
│ SERVER-ONLY (not in vault): │
│ • templates/repo/vault/feature_upgrade.tmpl │
│ • templates/repo/vault/not_installed.tmpl │
│ • templates/repo/vault/upgrade.tmpl │
│ • routers/web/repo/vault/vault.go ← Router glue code │
│ • services/vault/vault.go ← Service wrappers │
└─────────────────────────────────────────────────────────────────┘
```
**When making changes:**
- Edit templates/locales in **gitcaddy-vault** (this repo)
- The CI build automatically syncs to gitcaddy-server
- Server-specific templates (upgrade prompts) stay in server repo
- Go router code stays in server repo (thin integration layer)
**Why not Go plugins?**
Go plugins require exact compiler version and dependency matches between plugin and host. This is fragile in practice, so we compile vault directly into the server binary.
### Building
The Vault module is compiled directly into GitCaddy Server. To build the server with Vault: