Skip to content

Commit 8cbf93e

Browse files
josecelanojosecelano
committed
docs: add comprehensive documentation index and update AGENTS.md
- Create docs/README.md as the main documentation entry point with: - Quick reference table for finding the right document - Documentation directory structure overview - Documentation organized by category (Users, Contributors, Maintainers, Researchers) - Quick navigation by task table - Complete detailed inventory in collapsible sections (160+ files) - Add Documentation section to AGENTS.md with: - Link to comprehensive documentation index - Documentation by category summary - Quick navigation by task table for common development activities - Improve documentation discoverability for all project stakeholders
1 parent ed5a0e0 commit 8cbf93e

File tree

2 files changed

+314
-0
lines changed

2 files changed

+314
-0
lines changed

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,3 +144,52 @@ These principles should guide all development decisions, code reviews, and featu
144144
- Cleanup procedures for both application and LXD resources
145145

146146
Follow the project conventions and ensure all checks pass.
147+
148+
## 📚 Documentation
149+
150+
The project has comprehensive documentation organized in the [`docs/`](docs/) directory. See the complete [Documentation Index](docs/README.md) for detailed navigation.
151+
152+
### Documentation by Category
153+
154+
**For Users:**
155+
156+
- Getting started: [`docs/user-guide/README.md`](docs/user-guide/README.md), [`docs/user-guide/quick-start.md`](docs/user-guide/quick-start.md)
157+
- Commands: [`docs/user-guide/commands/`](docs/user-guide/commands/), [`docs/console-commands.md`](docs/console-commands.md)
158+
- Providers: [`docs/user-guide/providers/`](docs/user-guide/providers/)
159+
160+
**For Contributors:**
161+
162+
- Contributing Guide: [`docs/contributing/README.md`](docs/contributing/README.md)
163+
- Architecture: [`docs/codebase-architecture.md`](docs/codebase-architecture.md), [`docs/contributing/ddd-layer-placement.md`](docs/contributing/ddd-layer-placement.md)
164+
- Testing: [`docs/contributing/testing/`](docs/contributing/testing/), [`docs/e2e-testing/`](docs/e2e-testing/)
165+
- Code Quality: [`docs/contributing/linting.md`](docs/contributing/linting.md), [`docs/development-principles.md`](docs/development-principles.md)
166+
167+
**For Maintainers:**
168+
169+
- Decisions: [`docs/decisions/`](docs/decisions/) (30+ ADRs)
170+
- Features: [`docs/features/`](docs/features/) (active and planned features)
171+
- Refactoring: [`docs/refactors/`](docs/refactors/) (ongoing improvements)
172+
- Roadmap: [`docs/roadmap.md`](docs/roadmap.md)
173+
174+
**For Researchers/Architects:**
175+
176+
- Research: [`docs/research/`](docs/research/) (testing strategies, UX patterns, MVVM analysis)
177+
- Analysis: [`docs/analysis/`](docs/analysis/) (code structure analysis)
178+
- Vision: [`docs/vision-infrastructure-as-software.md`](docs/vision-infrastructure-as-software.md)
179+
180+
### Quick Navigation by Task
181+
182+
| Task | Start Here |
183+
| ------------------------- | ---------------------------------------------------------------------------------------- |
184+
| Start using the deployer | [`docs/user-guide/README.md`](docs/user-guide/README.md) |
185+
| Contribute code | [`docs/contributing/README.md`](docs/contributing/README.md) |
186+
| Understand architecture | [`docs/codebase-architecture.md`](docs/codebase-architecture.md) |
187+
| Add code to correct layer | [`docs/contributing/ddd-layer-placement.md`](docs/contributing/ddd-layer-placement.md) |
188+
| Run E2E tests | [`docs/e2e-testing/README.md`](docs/e2e-testing/README.md) |
189+
| Write unit tests | [`docs/contributing/testing/unit-testing.md`](docs/contributing/testing/unit-testing.md) |
190+
| Understand a decision | [`docs/decisions/README.md`](docs/decisions/README.md) |
191+
| Plan a new feature | [`docs/features/README.md`](docs/features/README.md) |
192+
| Fix a CI issue | [`docs/github-actions-issues/README.md`](docs/github-actions-issues/README.md) |
193+
| Work with templates | [`docs/contributing/templates.md`](docs/contributing/templates.md) |
194+
| Handle errors properly | [`docs/contributing/error-handling.md`](docs/contributing/error-handling.md) |
195+
| Organize Rust modules | [`docs/contributing/module-organization.md`](docs/contributing/module-organization.md) |

‎docs/README.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# Documentation Index
2+
3+
Welcome to the Torrust Tracker Deployer documentation! This index helps you quickly find the right documentation for your needs.
4+
5+
## 📚 Quick Reference
6+
7+
### 🎯 Most Important Documents (Read These First)
8+
9+
| When You Need To... | Read This Document |
10+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
11+
| Understand the codebase architecture | [`codebase-architecture.md`](codebase-architecture.md) - DDD layers, module organization |
12+
| Place code in the correct layer | [`contributing/ddd-layer-placement.md`](contributing/ddd-layer-placement.md) - **CRITICAL** decision flowchart |
13+
| Follow development principles | [`development-principles.md`](development-principles.md) - Observability, Testability, User Friendliness, Actionability |
14+
| Commit code | [`contributing/commit-process.md`](contributing/commit-process.md) - Pre-commit checks, conventional commits |
15+
| Handle errors properly | [`contributing/error-handling.md`](contributing/error-handling.md) - Explicit enums, actionable messages |
16+
| Organize Rust code | [`contributing/module-organization.md`](contributing/module-organization.md) - **CRITICAL** import conventions |
17+
| Work with templates | [`contributing/templates.md`](contributing/templates.md) - **CRITICAL** Tera syntax, registration |
18+
| Write unit tests | [`contributing/testing/unit-testing.md`](contributing/testing/unit-testing.md) - Naming conventions (no `test_` prefix!) |
19+
| Run E2E tests | [`e2e-testing/README.md`](e2e-testing/README.md) - Quick start, test suites |
20+
| Understand a past decision | [`decisions/README.md`](decisions/README.md) - 30+ ADRs indexed |
21+
| Use the CLI | [`user-guide/README.md`](user-guide/README.md) - Complete user guide |
22+
23+
### 📂 Documentation Directory Structure
24+
25+
```text
26+
docs/
27+
├── contributing/ 🤝 Contribution guidelines (branching, commits, DDD, errors, templates, testing)
28+
├── decisions/ 📋 Architectural Decision Records (30+ ADRs with context and rationale)
29+
├── e2e-testing/ 🧪 E2E test documentation (architecture, running, manual, troubleshooting)
30+
├── features/ ✨ Feature specifications and development tracking (5 active features)
31+
├── user-guide/ 📖 User documentation (commands, providers, quick start)
32+
├── tech-stack/ 🛠️ Technology docs (Ansible, LXD, OpenTofu, SSH)
33+
├── technical/ 🔧 Technical deep dives (template system, type erasure patterns)
34+
├── research/ 🔬 Research notes (Ansible testing, UX patterns, MVVM analysis)
35+
├── refactors/ 🔄 Refactoring plans and tracking
36+
├── implementation-plans/ 📝 Step-by-step plans for complex changes
37+
├── issues/ 📋 Issue templates and specifications
38+
├── github-actions-issues/ ⚠️ CI/CD troubleshooting
39+
└── analysis/ 📊 Code analysis (presentation layer structure)
40+
```
41+
42+
## 📚 Documentation by Category
43+
44+
### For Users
45+
46+
- **Getting Started**: [`user-guide/README.md`](user-guide/README.md), [`user-guide/quick-start.md`](user-guide/quick-start.md)
47+
- **Commands**: [`user-guide/commands/`](user-guide/commands/), [`console-commands.md`](console-commands.md)
48+
- **Providers**: [`user-guide/providers/`](user-guide/providers/)
49+
50+
### For Contributors
51+
52+
- **Contributing Guide**: [`contributing/README.md`](contributing/README.md)
53+
- **Architecture**: [`codebase-architecture.md`](codebase-architecture.md), [`contributing/ddd-layer-placement.md`](contributing/ddd-layer-placement.md)
54+
- **Testing**: [`contributing/testing/`](contributing/testing/), [`e2e-testing/`](e2e-testing/)
55+
- **Code Quality**: [`contributing/linting.md`](contributing/linting.md), [`development-principles.md`](development-principles.md)
56+
57+
### For Maintainers
58+
59+
- **Decisions**: [`decisions/`](decisions/) (30+ ADRs)
60+
- **Features**: [`features/`](features/) (active and planned features)
61+
- **Refactoring**: [`refactors/`](refactors/) (ongoing improvements)
62+
- **Roadmap**: [`roadmap.md`](roadmap.md)
63+
64+
### For Researchers/Architects
65+
66+
- **Research**: [`research/`](research/) (testing strategies, UX patterns, MVVM analysis)
67+
- **Analysis**: [`analysis/`](analysis/) (code structure analysis)
68+
- **Vision**: [`vision-infrastructure-as-software.md`](vision-infrastructure-as-software.md)
69+
70+
## 🎯 Quick Navigation by Task
71+
72+
### "I want to..."
73+
74+
| Task | Start Here |
75+
| ------------------------- | ------------------------------------------------------------------------------ |
76+
| Start using the deployer | [`user-guide/README.md`](user-guide/README.md) |
77+
| Contribute code | [`contributing/README.md`](contributing/README.md) |
78+
| Understand architecture | [`codebase-architecture.md`](codebase-architecture.md) |
79+
| Add code to correct layer | [`contributing/ddd-layer-placement.md`](contributing/ddd-layer-placement.md) |
80+
| Run E2E tests | [`e2e-testing/README.md`](e2e-testing/README.md) |
81+
| Write unit tests | [`contributing/testing/unit-testing.md`](contributing/testing/unit-testing.md) |
82+
| Understand a decision | [`decisions/README.md`](decisions/README.md) |
83+
| Plan a new feature | [`features/README.md`](features/README.md) |
84+
| Fix a CI issue | [`github-actions-issues/README.md`](github-actions-issues/README.md) |
85+
| Work with templates | [`contributing/templates.md`](contributing/templates.md) |
86+
| Handle errors properly | [`contributing/error-handling.md`](contributing/error-handling.md) |
87+
| Organize Rust modules | [`contributing/module-organization.md`](contributing/module-organization.md) |
88+
89+
---
90+
91+
## 📋 Complete Documentation Inventory
92+
93+
<details>
94+
<summary><strong>📁 Root Level Documentation (Click to Expand)</strong></summary>
95+
96+
| File | Description |
97+
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98+
| [`codebase-architecture.md`](codebase-architecture.md) | Comprehensive overview of DDD architecture, layer structure (Domain, Application, Infrastructure, Presentation), and module organization |
99+
| [`console-commands.md`](console-commands.md) | Complete reference for CLI commands, deployment states, and implementation status of all commands (create, provision, configure, release, run, destroy, etc.) |
100+
| [`deployment-overview.md`](deployment-overview.md) | High-level overview of deployment lifecycle states, command relationships, and state transitions with visual diagrams |
101+
| [`development-principles.md`](development-principles.md) | Core principles: Observability, Testability, User Friendliness, Actionability - guiding all development decisions and code quality standards |
102+
| [`documentation.md`](documentation.md) | Guide explaining documentation organization structure, categories, and where to place different types of documentation |
103+
| [`linting.md`](linting.md) | Linting tool usage, configuration files, and quick commands for maintaining code quality across all file types |
104+
| [`roadmap.md`](roadmap.md) | Development roadmap with epics, features, and implementation status tracking |
105+
| [`roadmap-questions.md`](roadmap-questions.md) | Open questions and discussions about roadmap priorities and future development direction |
106+
| [`tofu-lxd-configuration.md`](tofu-lxd-configuration.md) | OpenTofu configuration details for LXD provider setup and usage |
107+
| [`vision-infrastructure-as-software.md`](vision-infrastructure-as-software.md) | Long-term vision for evolving Infrastructure as Code to Infrastructure as Software with DDD principles |
108+
| [`vm-providers.md`](vm-providers.md) | Overview of supported VM providers (LXD, Hetzner) and provider architecture |
109+
110+
</details>
111+
112+
<details>
113+
<summary><strong>🤝 Contributing Guidelines (18 documents) (Click to Expand)</strong></summary>
114+
115+
Essential guides: DDD layer placement, module organization, error handling, templates, commit process, testing conventions
116+
117+
**Key Documents:**
118+
119+
- [`contributing/README.md`](contributing/README.md) - Quick reference guide to all contribution documentation
120+
- [`contributing/ddd-layer-placement.md`](contributing/ddd-layer-placement.md) - **CRITICAL**: Rules for placing code in correct DDD layers
121+
- [`contributing/module-organization.md`](contributing/module-organization.md) - **CRITICAL**: Module organization and Rust import patterns
122+
- [`contributing/templates.md`](contributing/templates.md) - **CRITICAL**: Tera template syntax and registration
123+
- [`contributing/error-handling.md`](contributing/error-handling.md) - Error handling principles
124+
- [`contributing/commit-process.md`](contributing/commit-process.md) - Commit process and pre-commit checks
125+
- [`contributing/testing/unit-testing.md`](contributing/testing/unit-testing.md) - Unit testing conventions
126+
127+
</details>
128+
129+
<details>
130+
<summary><strong>📋 Architectural Decision Records (30+ ADRs) (Click to Expand)</strong></summary>
131+
132+
Index at [`decisions/README.md`](decisions/README.md) - All architectural decisions documented with context, rationale, and consequences
133+
134+
**Recent Notable Decisions:**
135+
136+
- Cloud-Init SSH Port Configuration with Reboot
137+
- Single Docker Image for Sequential E2E Command Testing
138+
- Register Command SSH Port Override
139+
- Migration to AGENTS.md Standard
140+
- ReentrantMutex Pattern for UserOutput
141+
- Environment Variable Prefix (`TORRUST_TD_`)
142+
- Command State Return Pattern
143+
- Actionable Error Messages
144+
- LXD VMs over Containers
145+
- Tera Minimal Templating Strategy
146+
147+
</details>
148+
149+
<details>
150+
<summary><strong>🧪 E2E Testing Documentation (8 documents) (Click to Expand)</strong></summary>
151+
152+
Architecture, running tests, manual testing, troubleshooting, test suites, contributing, advanced techniques
153+
154+
**Key Documents:**
155+
156+
- [`e2e-testing/README.md`](e2e-testing/README.md) - Overview and quick start
157+
- [`e2e-testing/running-tests.md`](e2e-testing/running-tests.md) - How to run automated tests
158+
- [`e2e-testing/manual-testing.md`](e2e-testing/manual-testing.md) - Manual testing guide
159+
- [`e2e-testing/troubleshooting.md`](e2e-testing/troubleshooting.md) - Common issues and solutions
160+
- [`e2e-testing/architecture.md`](e2e-testing/architecture.md) - Testing architecture and design
161+
162+
</details>
163+
164+
<details>
165+
<summary><strong>✨ Feature Development (7+ features) (Click to Expand)</strong></summary>
166+
167+
Feature specs, templates, 5 active features
168+
169+
**Active Features:**
170+
171+
- Hetzner Provider Support
172+
- Import Existing Instances
173+
- Hybrid Command Architecture
174+
- Linter Auto-fix
175+
- Linter Parallel Execution (deferred)
176+
- Environment State Management (refactoring)
177+
- Progress Reporting in Application Layer
178+
179+
See [`features/README.md`](features/README.md) for complete list and templates.
180+
181+
</details>
182+
183+
<details>
184+
<summary><strong>📖 User Documentation (Click to Expand)</strong></summary>
185+
186+
Complete user guide with command documentation, provider guides, quick start, logging, template customization
187+
188+
**Key Documents:**
189+
190+
- [`user-guide/README.md`](user-guide/README.md) - Complete user guide
191+
- [`user-guide/quick-start.md`](user-guide/quick-start.md) - Quick start guide
192+
- [`user-guide/commands/`](user-guide/commands/) - Individual command documentation (8 commands)
193+
- [`user-guide/providers/`](user-guide/providers/) - Provider-specific guides (LXD, Hetzner)
194+
195+
</details>
196+
197+
<details>
198+
<summary><strong>🛠️ Technology Documentation (4 documents) (Click to Expand)</strong></summary>
199+
200+
Ansible, LXD, OpenTofu, SSH keys - installation, setup, and usage
201+
202+
- [`tech-stack/ansible.md`](tech-stack/ansible.md)
203+
- [`tech-stack/lxd.md`](tech-stack/lxd.md)
204+
- [`tech-stack/opentofu.md`](tech-stack/opentofu.md)
205+
- [`tech-stack/ssh-keys.md`](tech-stack/ssh-keys.md)
206+
207+
</details>
208+
209+
<details>
210+
<summary><strong>🔧 Technical Deep Dives (2 documents) (Click to Expand)</strong></summary>
211+
212+
- [`technical/template-system-architecture.md`](technical/template-system-architecture.md) - **CRITICAL**: Template system architecture and Project Generator pattern
213+
- [`technical/type-erasure-pattern.md`](technical/type-erasure-pattern.md) - Type erasure pattern for Environment states
214+
215+
</details>
216+
217+
<details>
218+
<summary><strong>🔬 Research Notes (Click to Expand)</strong></summary>
219+
220+
Ansible testing strategy, Docker vs LXD, E2E testing, UX patterns, MVVM analysis, presentation layer organization
221+
222+
**Key Documents:**
223+
224+
- [`research/ansible-testing-strategy.md`](research/ansible-testing-strategy.md) - Comprehensive Ansible testing strategy
225+
- [`research/docker-vs-lxd-ansible-testing.md`](research/docker-vs-lxd-ansible-testing.md) - Technology comparison
226+
- [`research/UX/`](research/UX/) - UX research documents (console output patterns, logging strategy)
227+
- [`research/mvvm-pattern-analysis/`](research/mvvm-pattern-analysis/) - MVVM pattern research
228+
229+
</details>
230+
231+
<details>
232+
<summary><strong>🔄 Other Documentation Categories (Click to Expand)</strong></summary>
233+
234+
**Refactoring Plans:**
235+
236+
- [`refactors/README.md`](refactors/README.md) - Process, templates, active/completed refactorings
237+
238+
**Implementation Plans:**
239+
240+
- [`implementation-plans/README.md`](implementation-plans/README.md) - Step-by-step plans for complex changes
241+
242+
**Issue Documentation:**
243+
244+
- [`issues/`](issues/) - Templates for epics, issues, and specifications
245+
246+
**CI/CD Troubleshooting:**
247+
248+
- [`github-actions-issues/README.md`](github-actions-issues/README.md) - GitHub Actions runner issues
249+
250+
**Code Analysis:**
251+
252+
- [`analysis/presentation-layer/`](analysis/presentation-layer/) - Presentation layer structure analysis
253+
254+
</details>
255+
256+
---
257+
258+
## 📊 Statistics
259+
260+
- **Total Documentation Files**: 160+ markdown files
261+
- **Major Categories**: 13 top-level directories
262+
- **ADRs**: 30+ architectural decisions documented
263+
- **Active Features**: 5 features in various stages
264+
- **Test Documentation**: Comprehensive E2E testing guides
265+
- **Contribution Guides**: 18 contributor-focused documents

0 commit comments

Comments
 (0)