# Audit Firm v2 — Full Baseline (Tailwind CDN + HTML + API + Security + System Settings)

This baseline is designed to be a **stable v2 foundation** before adding other modules.

## What’s included
- FastAPI app with **HTML + API** side-by-side
- Tailwind CSS via **CDN**
- Modular templates: `app/ui/templates/modules/<module>/...`
- System Settings module (super-admin UI):
  - Tenants
  - Branches
  - Branch policies (identity, holidays, email policy, storage policy, security policy)
- Security (built-in):
  - Password hashing (bcrypt via passlib)
  - Session auth (browser UI) + CSRF protection for HTML forms
  - Secure cookie options (configurable) + security headers + CSP (Tailwind CDN allowed)
  - RBAC (roles/permissions) with default roles seeded:
    - System Admin, Firm Admin, Partner, Branch Manager, Staff, Client, Consultant
  - Login lockout policy (attempts + lockout minutes) enforced
  - Session expiry policy enforced (minutes)
  - OTP step (dev mode): OTP code is printed to console (placeholder for SMS/Email provider)

- DB:
  - Common DB via SQLAlchemy (SQLite now; Postgres later)
  - Tables are created on startup using `metadata.create_all()` to keep install smooth.
    (Next step: replace with Alembic common + year.)

- Tools:
  - Local Storage Agent generator (`tools/storage_agent/`)

## Quick start (Windows)
```bat
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

uvicorn app.main:app --reload
```

Open:
- http://127.0.0.1:8000/health
- http://127.0.0.1:8000/login
- http://127.0.0.1:8000/system-settings

Bootstrap admin (first run):
- Uses `BOOTSTRAP_ADMIN_EMAIL` and `BOOTSTRAP_ADMIN_PASSWORD` from `.env`

## OTP (dev placeholder)
If OTP is required for your role (see Branch Settings → Security Policy),
the app will show an OTP page after password login and print the OTP code in the console logs.

## JWT (API authentication)
Endpoints:
- POST `/api/auth/token`
- POST `/api/auth/refresh`
- POST `/api/auth/logout`
- GET  `/api/auth/me` (debug helper)

Notes:
- Access token is JWT (HS256) signed using `SECRET_KEY`
- Refresh token is opaque and stored hashed (sha256) in DB with rotation

## Template structure refactor
Templates are now organized as:
- `app/modules/system_settings/templates/...`
- `app/modules/core/iam/templates/...`
- `app/modules/core/audit/templates/...`
- shared base remains at `app/ui/templates/base/layout.html`

The Jinja loader resolves from `app/`, so module templates can safely extend:
`ui/templates/base/layout.html`

## Alembic added to baseline
This baseline now uses **Alembic for the Common DB from the beginning**.

### First-time setup
1. Create virtual environment and install requirements
2. Copy `.env.example` to `.env`
3. Run:
   `alembic upgrade head`
4. Start app:
   `uvicorn app.main:app --reload`

### Create a new migration
`alembic revision --autogenerate -m "message"`

### Apply migrations
`alembic upgrade head`

### Downgrade one step
`alembic downgrade -1`

### Windows helper scripts
- `scripts\migrate_up.bat`
- `scripts\new_migration.bat "message"`

### Important
- App startup no longer creates schema automatically.
- Schema must be migrated using Alembic first.
- This baseline adds **Common DB Alembic only**.
- `alembic_year/` for year databases can be added next.