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)

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

uvicorn app.main:app --reload

Open:

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

Create virtual environment and install requirements
Copy .env.example to .env
Run: alembic upgrade head
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.

3.3 KiB Raw Blame History Unescape Escape