docs: comprehensive documentation overhaul
Add complete documentation structure: - Frontend architecture documentation - Database schema documentation - Deployment guides (Docker, Traefik, Authentik, Environment) - Development guides (Setup, Testing, Contributing, Quality Gates) - Deployment architecture documentation - Updated docs README with complete navigation All new features and APIs are now documented. Quality gates: docs only, no code changes
This commit is contained in:
Fusion
@@ -0,0 +1,299 @@
|
||||
# Development Setup Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Node.js 18+
|
||||
- PostgreSQL 15+
|
||||
- Redis 7+
|
||||
- Git
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### 1. Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/headquarter.git
|
||||
cd headquarter
|
||||
```
|
||||
|
||||
### 2. Backend Setup
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux/Mac
|
||||
# .venv\Scripts\activate # Windows
|
||||
|
||||
# Install dependencies
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
### 3. Frontend Setup
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
### 4. Database Setup
|
||||
|
||||
```bash
|
||||
# Start PostgreSQL and Redis
|
||||
# (Using Docker or local installation)
|
||||
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=headquarter postgres:15
|
||||
docker run -d -p 6379:6379 redis:7
|
||||
|
||||
# Create database
|
||||
createdb headquarter
|
||||
|
||||
# Run migrations
|
||||
cd apps/api
|
||||
alembic upgrade head
|
||||
|
||||
# (Optional) Seed data
|
||||
python -m src.scripts.seed
|
||||
```
|
||||
|
||||
### 5. Start Development Servers
|
||||
|
||||
Terminal 1 - Backend:
|
||||
```bash
|
||||
cd apps/api
|
||||
source .venv/bin/activate
|
||||
python -m uvicorn src.main:app --reload --port 8000
|
||||
```
|
||||
|
||||
Terminal 2 - Frontend:
|
||||
```bash
|
||||
cd apps/web
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Terminal 3 - (Optional) Authentik:
|
||||
```bash
|
||||
# If using local Authentik
|
||||
docker compose -f docker-compose.authentik.yml up -d
|
||||
```
|
||||
|
||||
## Development Environment Variables
|
||||
|
||||
Create `apps/api/.env`:
|
||||
|
||||
```bash
|
||||
APP_ENV=development
|
||||
DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
SESSION_SECRET=dev-session-secret-change-me
|
||||
API_DOMAIN=localhost
|
||||
WEB_DOMAIN=localhost
|
||||
|
||||
# Authentik (optional for local dev)
|
||||
AUTHENTIK_DOMAIN=authentik.local
|
||||
AUTHENTIK_CLIENT_ID=headquarter-web
|
||||
AUTHENTIK_CLIENT_SECRET=change-me
|
||||
AUTHENTIK_APPLICATION_SLUG=headquarter-web
|
||||
```
|
||||
|
||||
Create `apps/web/.env`:
|
||||
|
||||
```bash
|
||||
VITE_API_BASE_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
## IDE Setup
|
||||
|
||||
### VS Code Extensions
|
||||
|
||||
Recommended extensions:
|
||||
- Python (ms-python.python)
|
||||
- Pylance (ms-python.vscode-pylance)
|
||||
- ESLint (dbaeumer.vscode-eslint)
|
||||
- Prettier (esbenp.prettier-vscode)
|
||||
- TypeScript Importer (pmneo.tsimporter)
|
||||
|
||||
### PyCharm/IntelliJ
|
||||
|
||||
1. Open `apps/api` as project
|
||||
2. Set Python interpreter to `.venv`
|
||||
3. Enable Django/Flask support for FastAPI
|
||||
|
||||
## Debugging
|
||||
|
||||
### Backend Debugging
|
||||
|
||||
**VS Code launch.json**:
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Python: FastAPI",
|
||||
"type": "python",
|
||||
"request": "launch",
|
||||
"module": "uvicorn",
|
||||
"args": ["src.main:app", "--reload", "--port", "8000"],
|
||||
"jinja": true,
|
||||
"justMyCode": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**PyCharm**:
|
||||
1. Run → Edit Configurations
|
||||
2. Add Python configuration
|
||||
3. Module name: `uvicorn`
|
||||
4. Parameters: `src.main:app --reload --port 8000`
|
||||
|
||||
### Frontend Debugging
|
||||
|
||||
**VS Code launch.json**:
|
||||
```json
|
||||
{
|
||||
"type": "chrome",
|
||||
"request": "launch",
|
||||
"name": "Launch Chrome against localhost",
|
||||
"url": "http://localhost:5173",
|
||||
"webRoot": "${workspaceFolder}/apps/web/src"
|
||||
}
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Database Migrations
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
|
||||
# Create new migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Downgrade
|
||||
alembic downgrade -1
|
||||
|
||||
# Current version
|
||||
alembic current
|
||||
|
||||
# History
|
||||
alembic history
|
||||
```
|
||||
|
||||
### Adding Dependencies
|
||||
|
||||
**Backend**:
|
||||
```bash
|
||||
cd apps/api
|
||||
# Add production dependency
|
||||
pip install package-name
|
||||
# Add to pyproject.toml [project.dependencies]
|
||||
|
||||
# Add dev dependency
|
||||
pip install -e ".[dev]"
|
||||
# Add to pyproject.toml [project.optional-dependencies.dev]
|
||||
```
|
||||
|
||||
**Frontend**:
|
||||
```bash
|
||||
cd apps/web
|
||||
npm install package-name
|
||||
npm install -D package-name # dev dependency
|
||||
```
|
||||
|
||||
### Git Workflow
|
||||
|
||||
1. Create feature branch: `git checkout -b feature/name`
|
||||
2. Make changes
|
||||
3. Run quality gates (see below)
|
||||
4. Commit: `git commit -m "feat: description"`
|
||||
5. Push: `git push origin feature/name`
|
||||
6. Create Pull Request
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
headquarter/
|
||||
├── apps/
|
||||
│ ├── api/ # Backend (FastAPI)
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── api/ # API routes
|
||||
│ │ │ ├── auth/ # Authentication
|
||||
│ │ │ ├── models/ # Database models
|
||||
│ │ │ ├── utils/ # Utilities
|
||||
│ │ │ └── main.py # Entry point
|
||||
│ │ ├── tests/ # Test suites
|
||||
│ │ ├── alembic/ # Migrations
|
||||
│ │ └── pyproject.toml # Dependencies
|
||||
│ └── web/ # Frontend (React)
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # API clients
|
||||
│ │ ├── components/ # React components
|
||||
│ │ ├── pages/ # Page components
|
||||
│ │ └── styles/ # CSS
|
||||
│ └── package.json # Dependencies
|
||||
├── docs/ # Documentation
|
||||
├── docker-compose.yml # Dev setup
|
||||
└── Makefile # Common commands
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Errors
|
||||
|
||||
```bash
|
||||
# Check PostgreSQL is running
|
||||
pg_isready -h localhost -p 5432
|
||||
|
||||
# Check credentials
|
||||
psql postgresql://headquarter:headquarter@localhost:5432/headquarter -c "SELECT 1"
|
||||
```
|
||||
|
||||
### Port Conflicts
|
||||
|
||||
```bash
|
||||
# Find process using port 8000
|
||||
lsof -i :8000
|
||||
|
||||
# Kill process
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Node Modules Issues
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
### Python Environment Issues
|
||||
|
||||
```bash
|
||||
cd apps/api
|
||||
rm -rf .venv
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
|
||||
- [React Documentation](https://react.dev/)
|
||||
- [SQLAlchemy Documentation](https://docs.sqlalchemy.org/)
|
||||
- [Alembic Documentation](https://alembic.sqlalchemy.org/)
|
||||
Reference in New Issue
Block a user