Redesign Docs (Freeze Mode)

STATUS: DESIGN FREEZE – Code here stays as-is. We are only improving the redesign docs until the new implementation repo is created.

These docs (Issue #31) explain where we are going and why. Keep it light, clear and useful for future contributors.

🔄 Repository Transition Strategy

This repository serves as the specification and design phase for the new production
system. Here's the complete transition plan:

1. Current Repository (torrust-tracker-deploy-bash-poc)

• Final Status: Will be archived as torrust-tracker-deploy-bash-poc-poc
• Purpose: Historical reference and complete specification for new system
• Contains: Complete documentation through Phase 4 (Goals → Requirements → Analysis → Design → Planning)
• Role: Blueprint and specification source for the new implementation

2. New Repository (torrust-tracker-installer)

• Purpose: Production-grade deployment system implementation
• Foundation: Copy of this redesign documentation as starting point
• Implementation Phases:
  • Phase 5: Implementation 🔨
  • Phase 6: Testing & Validation 🧪
  • Phase 7: Migration & Deployment 🚀

3. Documentation Handover

• What Transfers: All docs/redesign/ content copied to new repository
• What Stays: PoC code and configuration (for historical reference)
• Timing: After Phase 4 (Planning) completion in this repository

This approach separates specification (this repo) from implementation (new repo),
ensuring clean separation of concerns and clear project boundaries.

What You Can Do Now

You want to…	Allowed?	How
Improve existing redesign docs	✅	Edit files under docs/redesign/
Add a missing focused requirement (e.g. firewall)	✅	New file + link it here + reference #31
Add an ADR	✅	Follow ADR format; keep it short & scoped
Change PoC code / refactor	❌	Archived; will rebuild clean later
Bump dependencies / tooling	❌	Unless a security issue (then open issue first)
Modify scripts or tests	❌	Only if a doc would be incorrect otherwise

If something outside the list is really needed (security/legal), open an issue and we’ll list it below.

Current Focus

Closing Phase 1 (Requirements). Last gap just filled:

• Dynamic firewall / network exposure management → phase1-requirements/firewall-dynamic-handling.md

After a quick review we move to Phase 2 (measure current behaviour: performance, state, operational toil).

Folder Map

Folder	Purpose
phase0-goals/	Project goals & scope
phase1-requirements/	Agreed requirements & technical details
phase2-analysis/	(Next) What the PoC actually does / limits
phase3-design/	Future architecture sketches & decisions
phase4-planning/	Milestones & rollout plan
community-input/	Collected suggestions & feedback

Simple 8-Phase Flow

Specification & Design Phases (in this repository):

0. Goals & scope (what we're trying to achieve)
1. Requirements (what matters technically)
2. Analyse current PoC (truth vs assumptions)
3. Design new solution
4. Plan build & migration

Implementation Phases (in new torrust-tracker-installer repository):

1. Implementation (build the new system)
2. Testing & validation (comprehensive testing)
3. Migration & deployment (production rollout)

Next Up (Short List)

Item	Phase	Status
Runtime state & persistence inventory	2	Planned
Performance baseline (throughput/latency/resources)	2	Planned
Dynamic firewall ADR (pick final approach)	1	Pending review
Deployment topology options	3	Drafting
Build graph / incremental strategy	3	Backlog

Related

• Master issue: #31 – Redesign

Exceptional Changes (none)

Empty. Add entries here only if an approved out‑of‑scope change happens.