crm-system/README.md

# CRM System v1.0

> Self-hosted CRM for small sales teams (5–25 sales reps).
> Stack: FastAPI + SQLAlchemy (async) + Alembic + Pydantic v2 + SQLite/PostgreSQL + Alpine.js + Tailwind + Docker + Coolify

## Quick Start (Development)

### 1. Clone and Setup

```bash
git clone <repo-url> crm-system
cd crm-system

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt -r requirements-dev.txt
```

### 2. Configure Environment

```bash
# Copy template
cp .env.example .env

# Generate a secure AUTH_SECRET (min 32 chars)
python3 -c "import secrets; print('AUTH_SECRET=' + secrets.token_urlsafe(48))" >> .env

# Edit .env and set AUTH_SECRET (remove the placeholder line first)
```

### 3. Initialize Database

```bash
# Apply migrations
alembic upgrade head

# (Optional) Create migration after model changes
# alembic revision --autogenerate -m "description"
```

### 4. Run Server

```bash
# Development with auto-reload
uvicorn app.main:app --reload --port 8000

# Production-like
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2
```

Open:
- API: http://localhost:8000
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- Health: http://localhost:8000/health

### 5. Bootstrap First User

```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "secure-password-123",
    "name": "First Admin"
  }'
```

This creates the first user + a default org. After that, registration is disabled (use admin invite flow in v1.1).

## Project Structure

```
crm-system/
├── app/                      # Application package
│   ├── main.py               # FastAPI entry point
│   ├── core/                 # Core modules (config, db, security, deps)
│   ├── models/               # SQLAlchemy models
│   ├── schemas/              # Pydantic schemas (request/response)
│   ├── services/             # Business logic layer
│   ├── api/v1/               # API routers (versioned)
│   └── webui/                # Static frontend (Phase 4c)
├── alembic/                  # Database migrations
│   ├── env.py                # Async migration environment
│   └── versions/             # Migration scripts
├── tests/                    # Test suite (pytest + pytest-asyncio)
├── requirements.txt          # Production dependencies
├── requirements-dev.txt      # Test/lint dependencies
├── pyproject.toml            # Tool configuration
├── alembic.ini               # Alembic configuration
├── .env.example              # Environment template
└── README.md
```

## Testing

```bash
# Run all tests
pytest -v --tb=short

# Run with coverage
pytest --cov=app --cov-report=term-missing

# Run specific test file
pytest tests/test_auth.py -v

# Stop on first failure (for debugging)
pytest -x
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `AUTH_SECRET` | ✅ | – | JWT signing secret (≥32 chars). Hard-fail if missing. |
| `DATABASE_URL` | ❌ | `sqlite+aiosqlite:///./dev.db` | Async DB URL (aiosqlite or asyncpg) |
| `JWT_ALGORITHM` | ❌ | `HS256` | JWT algorithm |
| `JWT_EXPIRY_HOURS` | ❌ | `24` | Token lifetime |
| `BCRYPT_ROUNDS` | ❌ | `12` | Password hashing cost |
| `CORS_ORIGINS` | ❌ | `http://localhost:5500,http://localhost:8000` | Allowed origins (comma-separated, NO wildcards) |
| `ENVIRONMENT` | ❌ | `development` | `development` or `production` |
| `LOG_LEVEL` | ❌ | `INFO` | Python log level |

## Architecture Decisions (ADR)

- **JWT Library**: `python-jose[cryptography]==3.3.0` (pattern reuse from wochenplaner)
- **Database**: SQLite (aiosqlite) for dev, PostgreSQL (asyncpg) for prod
- **Auth**: Stateless JWT in localStorage, bcrypt password hashing (12 rounds)
- **Security**: CORS whitelist (no wildcard), CSP middleware, no default admin user
- **Async**: All routers/services/DB operations are async (SQLAlchemy 2.0 + aiosqlite)

See `/a0/.a0/02-architecture.md` Section 13 for full lockdown decisions.

## Deployment

See `/a0/.a0/03-task-graph.json` Phase 4d for Docker + Coolify setup (out of scope for Phase 4a).

## License

Internal project – proprietary.