# Headquarter

A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication.

## Overview

Headquarter provides a centralized workspace for development teams to:
- Manage projects and their associated git repositories
- Browse repository files and view git history
- Spawn development tools (VS Code Server, Jupyter Notebook, etc.)
- Manage SSH keys and user preferences

## Features

### Project Management
- Create and manage projects
- View all projects in a dashboard
- Click any project to open its workspace

### Git Repository Management
- Initialize bare repositories
- Clone repositories (including mirror clones)
- Smart URL parsing (converts browser URLs to git URLs)
- View repository history and commit details

### Repository Workspace
- Browse files and directories
- View file contents with syntax highlighting
- Switch between branches
- Quick file editing with automatic commits

### Git History Visualization
- View commit history with branch graph
- See commit details, statistics, and diffs
- Filter by branch

### Authentication
- OAuth2 via Authentik
- Session-based authentication
- User profile management

### Tool Management
- Built-in tool types (code-server, jupyter-notebook)
- Create custom tool types with Docker Compose templates
- Template validation

### User Settings
- Theme selection (system/light/dark)
- Git identity configuration
- Default editor preference

### SSH Key Management
- Generate Ed25519 key pairs
- Copy public keys to clipboard
- Delete keys

## Quick Start

### Prerequisites
- Docker and Docker Compose
- Git

### Local Development

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd headquarter
   ```

2. **Set up environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

3. **Start services:**
   ```bash
   docker compose up -d
   ```

4. **Access the application:**
   - Frontend: http://localhost:5173
   - API: http://localhost:8000
   - API Docs: http://localhost:8000/docs

### Production Deployment

See [Deployment Guide](docs/deployment/) for production setup with Traefik and Authentik.

## Tech Stack

### Backend
- **FastAPI** - Python web framework
- **SQLAlchemy** - ORM with async PostgreSQL support
- **Pydantic** - Data validation
- **Alembic** - Database migrations
- **python-jose** - JWT handling

### Frontend
- **React** - UI library
- **TypeScript** - Type safety
- **Vite** - Build tool
- **React Router** - Client-side routing

### Infrastructure
- **Docker** - Containerization
- **PostgreSQL** - Database
- **Traefik** - Reverse proxy (production)
- **Authentik** - Identity provider

## Documentation

- [User Guide](docs/features/) - Feature documentation
- [API Reference](docs/api/) - API endpoints
- [Architecture](docs/architecture/) - System design
- [Deployment](docs/deployment/) - Setup guides
- [Development](docs/development/) - Contributing

## Project Structure

```
.
├── apps/
│   ├── api/              # FastAPI backend
│   │   ├── src/
│   │   │   ├── api/      # API routes
│   │   │   ├── auth/     # Authentication
│   │   │   ├── models/   # Database models
│   │   │   └── utils/    # Utilities
│   │   ├── tests/        # Test suite
│   │   └── Dockerfile
│   └── web/              # React frontend
│       ├── src/
│       │   ├── api/      # API clients
│       │   ├── components/# UI components
│       │   └── pages/    # Page components
│       └── Dockerfile
├── docs/                 # Documentation
├── docker-compose.yml    # Development setup
├── docker-compose.traefik.yml  # Production setup
└── Makefile             # Common commands
```

## Development

### Backend Development
```bash
cd apps/api
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn src.main:app --reload
```

### Frontend Development
```bash
cd apps/web
npm install
npm run dev
```

### Running Tests
```bash
# Backend tests
make test

# Frontend tests
make test-web

# All quality gates
make lint
make typecheck
```

## Configuration

Key environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `API_DOMAIN` | API domain | `localhost` |
| `WEB_DOMAIN` | Web domain | `localhost` |
| `AUTHENTIK_DOMAIN` | Authentik domain | - |
| `AUTHENTIK_CLIENT_ID` | OAuth client ID | - |
| `AUTHENTIK_CLIENT_SECRET` | OAuth client secret | - |
| `DATABASE_URL` | PostgreSQL URL | - |
| `JWT_SECRET` | JWT signing secret | - |
| `REPO_BASE_PATH` | Repository storage path | `/data/repos` |

See [Environment Variables](docs/deployment/environment.md) for complete list.

## License

[License information]