---
name: project-documentation
description: Standard project folder structure and documentation requirements for ITPP projects — every project gets README, CHANGELOG, ARCHITECTURE, DECISIONS, ROADMAP, and GLOSSARY as appropriate.
version: 1.0.0
author: Sho'Nuff
tags: [documentation, projects, standards, readme, changelog, architecture]
---

# Project Documentation Standards

Every ITPP project lives self-contained under `/root/projects/<name>/`. Each project folder is backed up daily at 3 AM via root-essentials-backup.sh and synced to S3.

## Required Files Per Project

Not every project needs every file. Create what's appropriate:

| File | When to create | Content |
|---|---|---|
| **README.md** | Always | One-paragraph summary, owner, status (LIVE/DEV/PLANNED), deployment URL, key contacts, access instructions (see below) |
| **CHANGELOG.md** | Always | Reverse-chronological entries: date, category, what changed. Pull from session history |
| **ARCHITECTURE.md** | Complex systems | System design, data flow, components, ASCII topology diagram |
| **DECISIONS.md** | Any key choice made | Why specific technology/service/architecture was chosen (ADR format) |
| **ROADMAP.md** | Active development | Planned features, milestones, priorities. Essential for ideation/sharing with partners |
| **GLOSSARY.md** | Domain-heavy projects | Terms that outsiders won't know (legal, technical, domain-specific) |

### README Access Section

Every project README MUST include basic access instructions. Someone reading the README should be able to reach and use the resource without asking follow-up questions.

**For web services/apps** — a table with URL, where it's hosted, and how to log in:

```markdown
## Access

| Resource | URL | Access |
|---|---|---|
| DRE Portal | https://portal.debtrecoveryexperts.com | Germaine (admin), Tony (read) |
| Client Email | dre@germainebrown.com | Polled every 60s |
```

**For MCP servers / APIs** — how to reach them, how they're wired, how to test:

```markdown
## Access

### In Open WebUI
All MCPs are wired into Open WebUI at http://ai.itpropartner.com.

### Adding a new MCP
1. Build and start the MCP service in docker-compose.yml
2. Insert connection into SQLite webui.db → config.key = 'tool_server.connections'
3. Restart Open WebUI

### Direct access (testing)
curl http://127.0.0.1:8899/mcp   # Super Search
```

**For infrastructure docs** — catalog all services with their URLs and credential locations:

```markdown
## Service Access

| Service | URL | Location | Notes |
|---|---|---|---|
| Open WebUI | http://ai.itpropartner.com | app1 | User-facing chat UI |
| Open WebUI Admin | https://admin-ai.itpropartner.com/ui | app1 | user: admin, pw: LiteLLM master key |
```

**Key principles:**
- URLs go in the README — not hidden in a separate file or only in memory
- Credential locations (e.g. "in Vaultwarden under info@itpropartner.com") are fine — never paste actual passwords
- If a resource has no public URL yet (PLANNED projects), say so: `**Deployed:** TBD`
- For MCPs/APIs, include a one-line curl test so anyone can verify it's alive
- For cross-referenced services, link to the other project's README

## Current Project Folders (Jul 10, 2026)

```
/root/projects/
  ├── dre/          Debt Recovery Experts
  ├── shark-game/   Shark Attack Fantasy League
  ├── itpp-infra/   IT Pro Partner Infrastructure
  ├── osint-tool/   OSINT People Search
  ├── apex-track/   Apex Track Experience
  ├── boxpilot/     BoxPilot Logistics
  └── README.md     Master index of all projects
```

## When to Create a New Project

- A distinct business line or product
- A tool/service that needs handoff to another person
- Something with its own domain, database, or deployment

## Documentation as Handoff

These documents exist so someone else (Tony, Ryan, a future sysadmin) can:
1. Read `README.md` → understand what this is in 60 seconds
2. Read `ARCHITECTURE.md` → understand how it works
3. Read `DECISIONS.md` → understand why choices were made
4. Read `ROADMAP.md` → understand what's coming next

Each document should stand alone. Assume the reader has zero context.

## Standing Order — Document as You Work

**Documentation is not a separate step.** It happens inline with the work, not as a post-hoc task the user has to ask for. When the Master says "isn't that part of your standing order?", it means:

1. **Create the project folder BEFORE starting work.** `/root/projects/<name>/` with at least `README.md` and `CHANGELOG.md` must exist at project kickoff, not mid-migration.
2. **Update IP/DNS changes** (`/root/.hermes/references/ip-dns-changes.md`) immediately when DNS records are updated, servers are migrated, or ports/services change
3. **Update master-apps-services.md** when adding, removing, or migrating services between servers
4. **Update project-log.md** with a dated entry summarizing every material change — what was done, why, what was affected
5. **Update project READMEs** when architecture decisions are made, status changes, or new patterns emerge
6. **Save to memory** any server-specific configuration that would be hard to rediscover (firewall rules, cert locations, backup paths, connection strings)

These updates happen in the same work session as the change itself, not after. If a change is complex enough to warrant documentation, the documentation update is part of the same tool call batch.

**CHANGELOG format:** Reverse-chronological entries. Each entry includes date, phase/step, obstacle, fix/decision, and status. See `/root/projects/hudu/CHANGELOG.md` for the current reference example.

## Scripts Inventory

All scripts MUST be documented in `/root/projects/scripts/README.md` — a master inventory organized by category (Backup & DR, Email, FleetTracker, Security, Monitoring, Ops Portal, etc.). Each entry includes: script name, type (shell/Python), purpose, and schedule. As of Jul 15, 2026: 74 scripts cataloged (40 shell, 34 Python). Update this inventory whenever a new script is added or an existing one is modified.

## Infrastructure Documentation

The master infrastructure document lives at `/root/projects/itpp-infrastructure/README.md`. It covers: server inventory with specs, domain/DNS map, backup pipeline schedule, Caddy reverse proxy configuration, SSL management, SSH access, and firewall rules. Update when servers, domains, or network configuration change.

## Git Repository Strategy

All documentation should live in a public Git repository for redundancy and visibility:

```text
git.itpropartner.com (self-hosted Gitea — planned)
    ├── Primary — you own the data, you control access
    ├── Each project has its own repo with README + CHANGELOG + configs
    ├── Mirror to GitHub for public redundancy
    └── Backed up to S3 every 15 min
```

**Never commit secrets.** `.env` files become `.env.example` with placeholders. API keys, passwords, and tokens stay in Vaultwarden.

## Tracked Reference Files — Always Keep Current

| File | When to Update |
|---|---|
| `/root/.hermes/references/ip-dns-changes.md` | DNS record change, IP change, server migration |
| `/root/.hermes/references/master-apps-services.md` | Service added/removed/moved between servers |
| `/root/.hermes/projects-log.md` | Every session with material infrastructure or project changes |
| `/root/projects/<name>/README.md` | Project status change, architecture decision |

## Pitfalls

- **Don't scatter docs across /root/**. The `/root/projects/` structure was created Jul 10 to consolidate everything. Old files in `/root/` or `/root/.hermes/references/` should be migrated with symlinks left at their old locations.
- **Update the master `README.md`** at `/root/projects/README.md` whenever a new project folder is created or a project status changes.
- **Backup scope**: /root/projects/ is explicitly included in the root-essentials-backup.sh tarball. New large binary assets should be hosted elsewhere (S3, /var/www/).
- **Don't duplicate vendor docs**: ARCHITECTURE.md should describe YOUR system, not the tools you use. Reference vendor URLs, don't replicate their docs.
- **Don't wait to be asked.** If the change is big enough to mention in conversation, it's big enough to document. Being called out for missing docs is a failure mode, not a reminder.