Metadata-Version: 2.4
Name: fastapi-console
Version: 0.1.1
Summary: Drop-in admin panel for FastAPI + SQLAlchemy apps
License: MIT
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic==1.18.4
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: fastapi>=0.136.3
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: uvicorn>=0.49.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# FastAPI Admin — Agent Guide

## What This Project Is

A drop-in admin panel for FastAPI + SQLAlchemy apps. Register a model, get full CRUD UI, auth, permissions, and audit logging — no manual form or view definitions required.

## Spec Documents

| File | Covers |
|---|---|
| `fastapi_admin_core_spec.md` | The 3 core bets: auto-discovery, audit log + RBAC, modern UI. Start here. |
| `AUTH_RBAC_SYSTEM.md` | Auth model extensibility (built-in / extend / BYO), session flow, RBAC permission tables and checks |
| `FORM_WIDGET_SYSTEM.md` | Widget class layer → Jinja2 macro layer, form pipeline, validation, relationship widgets |
| `PLUGIN_SYSTEM.md` | Every extension point: widgets, hooks, routes, auth, storage, audit sinks, dashboard, UI |

## Architecture in One Paragraph

On startup, `Admin()` inspects every registered SQLAlchemy model, maps column types to widgets, and auto-generates CRUD routes under `/admin/{table}/`. Each request hits an auth middleware (session cookie → `AuthBackend.get_user`), then a `PermissionChecker` that reads `admin_permissions` rows keyed by `user.role_id`. Forms are rendered via `Widget.render_context()` → Jinja2 macros (Tailwind + HTMX + Alpine.js). Every DB write fires SQLAlchemy session events that write to `admin_audit_log`. Everything is replaceable via protocols.

## Key Concepts

- **RegisteredModel** — central dataclass holding the model class, its `ModelAdmin` config, inspected columns/relationships, and resolved widgets
- **Widget** — two-layer: Python class (parse + validate) + Jinja2 macro (HTML). Override either independently
- **PermissionChecker** — instantiated per request; checks `admin_permissions` table; superusers bypass all checks
- **AuthBackend** — two methods: `authenticate()` on login, `get_user()` on every request
- **AdminPlugin** — bundles widgets, macros, routes, nav items, hooks into a distributable package
- **AuditLog** — written via SQLAlchemy `after_flush` event; stores full snapshot + diff for UPDATEs

## Project Structure (key paths)

```
fastapi_admin/
├── admin.py          # Admin class, public API, wires everything at init
├── registry.py       # AdminRegistry singleton
├── inspection.py     # SQLAlchemy model → ColumnMeta / RelationMeta
├── field_types.py    # Column type → widget name mapping
├── router.py         # Auto-route generation per registered model
├── auth/             # AuthBackend, PermissionChecker, session, dependencies
├── audit/            # AuditLog model, SQLAlchemy event listener, diff, context
├── widgets/          # Widget base class, all built-in widgets, WidgetRegistry
├── views/            # Route handler factories (list, form, delete, roles, dashboard)
├── templates/        # Jinja2: base.html, pages/, partials/, macros/
└── static/           # Tailwind CSS, HTMX, Alpine.js, Heroicons
```

## Tech Stack

FastAPI · SQLAlchemy 2.x · Jinja2 · Tailwind CSS · HTMX · Alpine.js · itsdangerous · passlib/bcrypt . uv

## What to Build (suggested order)

1. `inspection.py` + `field_types.py` — model inspection and type→widget mapping
2. `registry.py` + `admin.py` — registration API and `ModelAdmin` base
3. `auth/` — models, session, `AuthBackend`, `PermissionChecker`, dependencies
4. `audit/` — listener, diff, `AuditLog` model
5. `widgets/` — base class, built-in widgets, `WidgetRegistry`
6. `views/` + `router.py` — route factories, form pipeline
7. `templates/` — Jinja2 templates and macros
8. `plugins/` — `AdminPlugin` base, plugin registration
