A R R R Associates
103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# 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.
|