Fusion
875594d66d
- Add CommitPanel component for viewing changed files and committing - Show file status indicators (M/A/D/?) in file tree - Integrate git status with workspace for real-time updates - Add CSS styles for commit panel and status badges Part of git-control change implementation.
155 lines
3.9 KiB
Markdown
155 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
# 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
|
|
```markdown
|
|
# 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
|
|
```markdown
|
|
## 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
|