106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# 🛡️ ZeroLagHub Drift Prevention - Quick Start Card
|
|
|
|
**Use This**: At the start of EVERY coding session (API, Agent, or Frontend)
|
|
|
|
---
|
|
|
|
## ⚡ 30-Second Architecture Check
|
|
|
|
### **Working on API?**
|
|
✅ Can allocate: Ports, VMIDs, DNS, Velocity
|
|
❌ Cannot: Install Java, download artifacts, exec in container
|
|
|
|
### **Working on Agent?**
|
|
✅ Can install: Java, artifacts, server files
|
|
❌ Cannot: Allocate ports, create DNS, call Proxmox, register Velocity
|
|
|
|
### **Working on Frontend?**
|
|
✅ Can: Display data, call API endpoints
|
|
❌ Cannot: Talk to Agent, Proxmox, DNS, Velocity, allocate anything
|
|
|
|
---
|
|
|
|
## 🔒 7 Locked Architectural Decisions (NEW) ⭐
|
|
|
|
**These decisions are FINAL** - cannot be changed without user saying "Revisit decision X":
|
|
|
|
1. **DEC-001**: Templates + Agent hybrid (not templates-only or agent-only)
|
|
2. **DEC-002**: API orchestrates, Agent executes (not reversed)
|
|
3. **DEC-003**: API owns DNS (Agent never creates DNS)
|
|
4. **DEC-004**: Traefik + Velocity only (no HAProxy)
|
|
5. **DEC-005**: MariaDB is source of truth (no flat files)
|
|
6. **DEC-006**: Frontend → API only (no direct agent calls)
|
|
7. **DEC-007**: Drift prevention mandatory (always enforced)
|
|
|
|
**If proposing change that conflicts with DEC-001 through DEC-007**:
|
|
→ STOP → Consult Cross-Project Tracker → Request "Revisit decision X" from user
|
|
|
|
---
|
|
|
|
## 🚨 Drift Detection Triggers
|
|
|
|
**STOP and consult full tracker if you hear:**
|
|
|
|
1. "Agent should allocate ports..."
|
|
2. "API should install Java inside container..."
|
|
3. "Frontend should call agent directly..."
|
|
4. "Agent should register with Velocity..."
|
|
5. "API should decide what Java version..."
|
|
6. "Frontend should manage DNS records..."
|
|
7. "Let's use templates only..." (violates DEC-001)
|
|
8. "Let's add HAProxy..." (violates DEC-004)
|
|
9. "Let's use flat files instead of DB..." (violates DEC-005)
|
|
|
|
**All of these are VIOLATIONS** → Consult [ZeroLagHub_Cross_Project_Tracker.md](computer:///mnt/user-data/outputs/ZeroLagHub_Cross_Project_Tracker.md)
|
|
|
|
---
|
|
|
|
## 📋 Pre-Coding Checklist
|
|
|
|
Before writing ANY code:
|
|
|
|
- [ ] Which system am I modifying? (API / Agent / Frontend)
|
|
- [ ] Does this change cross boundaries? (If yes → read full tracker)
|
|
- [ ] Am I adding external API calls to Agent? (If yes → VIOLATION)
|
|
- [ ] Am I adding container execution to API? (If yes → VIOLATION)
|
|
- [ ] Am I bypassing API in Frontend? (If yes → VIOLATION)
|
|
|
|
---
|
|
|
|
## 🎯 The Golden Rules
|
|
|
|
1. **API orchestrates** (allocates resources, publishes state)
|
|
2. **Agent executes** (installs, runs, monitors inside container)
|
|
3. **Frontend displays** (no direct infrastructure access)
|
|
|
|
**Anything else** → Drift → Consult full tracker
|
|
|
|
---
|
|
|
|
## 📞 Quick Reference
|
|
|
|
**Full Tracker**: [ZeroLagHub_Cross_Project_Tracker.md](computer:///mnt/user-data/outputs/ZeroLagHub_Cross_Project_Tracker.md)
|
|
|
|
**High-Risk Zones**:
|
|
- Forge/NeoForge installation
|
|
- Cloudflare SRV deletion
|
|
- Velocity registration order
|
|
- PortPool commit logic
|
|
- Agent READY detection
|
|
- IP selection logic
|
|
|
|
---
|
|
|
|
## ✅ Session Start Command
|
|
|
|
```
|
|
Read ZeroLagHub Cross-Project Tracker Quick Start Card.
|
|
Activate drift detection.
|
|
Confirm which system I'm working on: [API / Agent / Frontend]
|
|
Proceed with architecture-aligned implementation only.
|
|
```
|
|
|
|
---
|
|
|
|
🛡️ **Drift prevention ACTIVE. Proceed with confidence.**
|