headquarter/openspec/changes/archive/2026-05-19-documentation-overhaul/design.md

Documentation Overhaul - Design

Documentation Structure

docs/
├── README.md              # Documentation index
├── architecture/
│   ├── backend.md         # Backend architecture
│   ├── frontend.md        # Frontend architecture
│   ├── database.md        # Database schema
│   └── deployment.md      # Deployment architecture
├── features/
│   ├── projects.md        # Project management
│   ├── repositories.md    # Git repositories
│   ├── workspace.md       # Repository workspace
│   ├── git-history.md     # Git history visualization
│   ├── auth.md            # Authentication
│   ├── tool-types.md      # Tool type management
│   └── settings.md        # User settings
├── api/
│   ├── README.md          # API overview
│   ├── auth.md            # Auth endpoints
│   ├── projects.md        # Project endpoints
│   ├── repositories.md    # Repository endpoints
│   └── users.md           # User endpoints
├── deployment/
│   ├── docker.md          # Docker setup
│   ├── traefik.md         # Traefik configuration
│   ├── authentik.md       # Authentik setup
│   └── environment.md     # Environment variables
├── development/
│   ├── setup.md           # Development setup
│   ├── testing.md         # Testing strategy (moved from README)
│   ├── contributing.md    # How to contribute
│   └── quality-gates.md   # Code quality
└── templates/
    ├── feature-doc.md     # Template for new features
    ├── api-endpoint.md    # Template for API docs
    └── architecture.md    # Template for architecture docs

README.md Structure

# Headquarter

## Overview
Short description of what the project is and does.

## Features
- Feature 1 (with link to docs)
- Feature 2 (with link to docs)

## Quick Start
1. Clone repo
2. Copy .env.example to .env
3. docker compose up
4. Open http://localhost:5173

## Architecture
Link to architecture docs.

## Documentation
- [User Guide](docs/features/)
- [API Docs](docs/api/)
- [Deployment](docs/deployment/)
- [Development](docs/development/)

## Tech Stack
- Backend: FastAPI + SQLAlchemy + PostgreSQL
- Frontend: React + TypeScript + Vite
- Auth: Authentik (OAuth2)
- Deployment: Docker + Traefik

Documentation Templates

Feature Documentation Template

# Feature Name

## Overview
What does this feature do?

## How to Use
Step-by-step user guide.

## Screenshots/Diagrams
Visual aids.

## API Endpoints
Related API endpoints.

## Configuration
Relevant config options.

## Related Features
Links to related docs.

API Endpoint Template

## GET /api/endpoint

**Description:** What this endpoint does.

**Authentication:** Required/Optional

**Request:**
- Query params
- Body schema

**Response:**
- Success schema
- Error codes

**Example:**
```bash
curl /api/endpoint

## Auto-Documentation Process

For new features, documentation should be created:

1. **During implementation** (not after):
   - When creating a new feature, create its doc file
   - Use the template from docs/templates/
   - Update README features list

2. **In the same commit**:
   - Code changes + doc changes in same PR
   - Review docs alongside code

3. **Checklist**:
   - [ ] Feature doc created in docs/features/
   - [ ] API endpoints documented in docs/api/
   - [ ] README updated with feature link
   - [ ] Architecture doc updated if needed

## Maintenance

- **Monthly review**: Check for outdated docs
- **Version tracking**: Tag docs with app version
- **OpenSpec integration**: Link to OpenSpec changes for context

## Tools

- **Markdown**: All docs in Markdown
- **Mermaid**: Diagrams in Mermaid syntax
- **FastAPI docs**: Auto-generated from code
- **GitHub Pages**: Optional static site generation