arrr-erp/documents

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:

• 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.