fabrik-fastapi 1.0.0__tar.gz

fabrik_fastapi-1.0.0/ARCHITECTURE.md

@@ -0,0 +1,414 @@
+# Architecture de Fabrik
+
+> Document de reference sur les decisions de conception, le decoupage du code,
+> et le cycle de vie d'un projet genere.
+
+**Auteur :** Falandy Jean
+**Version :** 1.0.0
+
+---
+
+## 1. Philosophie
+
+Fabrik est un **opinionated framework** construit au-dessus de FastAPI. Il
+prend des decisions pour toi sur :
+
+- L'asynchronisme (tout est `async`, pas de blocage thread sur les I/O DB)
+- La structure de fichiers (`src/<module>/` avec separation
+  `models / schemas / service / router`)
+- La securite par defaut (CORS strict, SECRET_KEY 256 bits, bcrypt, JWT)
+- Les outils de developpement (tests isoles, migrations, admin UI)
+
+**Ce que Fabrik refuse de faire :**
+- Devenir un framework "universel" (pas de plugins, pas d'ecosysteme tiers)
+- Cacher SQLAlchemy ou FastAPI (tu vois et controle tout)
+- Etre retro-compatible avec les vieux Python (Python 3.13+ uniquement)
+
+---
+
+## 2. Decoupage du repo
+
+```
+fabrik/                          ← repo GitHub
+├── pyproject.toml               Metadata PyPI (nom, version, deps, entry_points)
+├── MANIFEST.in                  Inclusion de core/ dans la sdist
+├── README.md                    Vitrine + installation
+├── ARCHITECTURE.md              ← ce fichier
+├── LICENSE                      MIT
+├── docs/
+│   ├── USAGE.md                 Guide utilisateur complet
+│   └── PUBLISHING.md            Workflow de release PyPI
+├── .github/workflows/ci.yml     CI (lance test-self a chaque commit)
+└── fabrik/                      ← PACKAGE Python publie sur PyPI
+    ├── __init__.py              Version + exports
+    ├── __main__.py              Pour `python -m fabrik`
+    ├── scaffold.py              Moteur CLI
+    └── core/                    Templates copies dans chaque projet
+```
+
+Quand l'utilisateur fait `pip install fabrik-cli`, c'est le dossier
+**inner `fabrik/`** qui est installe dans le `site-packages` de son Python.
+La commande `fabrik` est creee par l'entry point `[project.scripts]` de
+`pyproject.toml` qui pointe vers `fabrik.scaffold:main`.
+
+### 2.1 Pourquoi `core/` est un dossier separe ?
+
+A la version 0 du prototype, **tous les templates etaient des chaines Python
+embarquees dans `scaffold.py`** (3902 lignes). Probleme :
+
+- Pas de coloration syntaxique dans l'IDE pour les templates Jinja2 / HTML / CSS
+- Difficile de chercher et editer un fichier specifique
+- Mauvais ratio signal/bruit a la lecture de `scaffold.py`
+
+Depuis v1.0, **les templates vivent comme de vrais fichiers dans `core/`** :
+
+- `core/<chemin>` -> fichier statique copie tel quel
+- `core/_templates/*.tpl` -> fichier avec substitution `string.Template`
+  (`${title}`, `${port}`, `${secret_key}`, `${db_url}`)
+
+`build_files()` est passe de 2750 lignes hardcodees a 20 lignes qui font un
+`rglob` sur `core/`.
+
+---
+
+## 3. Cycle de vie d'un projet
+
+### 3.1 `scaffold.py new mon-api`
+
+```
+   cmd_new()
+       │
+       ├── build_files(title, port, db_url)
+       │       └── walk core/ -> dict {chemin: contenu}
+       │       └── string.Template.substitute() pour core/_templates/*.tpl
+       │
+       ├── Pour chaque (chemin, contenu) : f.write_text(contenu)
+       │
+       ├── Ecrit .scaffold-version (JSON : version + date + patches_applied)
+       │
+       ├── subprocess: python -m venv venv
+       ├── subprocess: venv/pip install -r requirements.txt
+       └── subprocess: venv/python -m alembic revision/upgrade
+```
+
+### 3.2 `scaffold.py add videos` (depuis la racine du projet)
+
+```
+   cmd_add()
+       │
+       ├── Genere les 5 fichiers du module
+       │   (models.py, schemas.py, service.py, router.py, test_videos.py)
+       │   via les Templates string.Template MODULE_MODELS, MODULE_SCHEMAS, ...
+       │
+       ├── Auto-wiring (idempotent) :
+       │   ├── main.py             : ajoute import + include_router
+       │   ├── alembic/env.py      : ajoute import src.videos.models
+       │   └── src/users/models.py : ajoute relation back_populates
+       │
+       ├── subprocess: alembic revision --autogenerate -m add_videos
+       ├── subprocess: alembic upgrade head
+       └── subprocess: pytest tests/test_videos.py
+```
+
+L'auto-wiring utilise `_insert_after(content, anchor, new_line)` qui :
+1. Verifie que la ligne (strip) n'est pas deja presente dans le fichier
+2. Trouve la premiere occurrence de l'anchor
+3. Insere la nouvelle ligne juste apres
+
+Cette idempotence permet de relancer `add` sans dupliquer les imports.
+
+### 3.3 `scaffold.py upgrade` (depuis la racine du projet)
+
+```
+   cmd_upgrade()
+       │
+       ├── Lit .scaffold-version -> version courante du projet
+       ├── Compare avec SCAFFOLD_VERSION (constante en haut de scaffold.py)
+       ├── Si projet < scaffold :
+       │   └── Pour chaque patch dans PATCHES dont [from, to] est compris :
+       │       └── patch["apply"](root)   ← fonction idempotente
+       │       └── Met a jour .scaffold-version
+       │
+       └── Si projet >= scaffold : "deja a jour"
+```
+
+Les fonctions de patch :
+- Recoivent `root: Path` (racine du projet a patcher)
+- Doivent etre **idempotentes** : safe a relancer N fois
+- Doivent ecrire un backup `.bak` avant tout ecrasement destructif
+- Retournent un `dict {chemin: statut}` pour le rapport
+
+---
+
+## 4. Decisions de conception : le projet genere
+
+### 4.1 Pourquoi `src/<module>/` au lieu d'un layout plat ?
+
+Le decoupage en `models / schemas / service / router` impose **la separation
+des responsabilites** :
+
+- `models.py` : ORM SQLAlchemy (donnees + relations)
+- `schemas.py` : validation Pydantic (input/output API)
+- `service.py` : logique metier (operations sur la DB)
+- `router.py` : routes HTTP (mapping URL -> service)
+
+Effet de bord : chaque module est **extractible en microservice** plus tard
+sans refactor douloureux.
+
+### 4.2 Pourquoi tout en async ?
+
+FastAPI + Starlette + uvicorn sont conçus pour async. Une route sync bloque
+le worker pendant l'attente DB. Avec `AsyncSession` + `asyncpg`, un seul
+process Python peut servir des milliers de requetes/seconde.
+
+Cout : la syntaxe `await` partout, et `db.execute(select(...))` au lieu de
+`db.query(...).filter(...).all()`. Mais c'est le standard SQLAlchemy 2.0.
+
+### 4.3 Pourquoi un `lifespan` ?
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    await engine.dispose()
+```
+
+Le lifespan remplace l'ancien `@app.on_event("startup")` deprecie. Il :
+- Cree les tables si elles n'existent pas (utile en dev sans Alembic)
+- Garantit le `dispose()` du pool de connexions a l'arret (pas de leak)
+- Est `async` natif (vs les hooks synchrones de l'ancienne API)
+
+### 4.4 Pourquoi SECRET_KEY est generee a chaque `new` ?
+
+`secrets.token_urlsafe(32)` = 256 bits d'entropie. Chaque projet a son propre
+secret des le depart, jamais commit accidentellement (le `.env` est dans
+`.gitignore`). PyJWT exige 32+ bytes pour HMAC-SHA256.
+
+### 4.5 Pourquoi CORS strict par defaut ?
+
+```python
+BACKEND_CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+```
+
+Avec `allow_origins=["*"]` + `allow_credentials=True`, Starlette desactive
+silencieusement les cookies (specification CORS). En forcant une liste
+explicite, on evite cette piege ET on empeche un site malveillant de
+proxifier l'API au nom de l'utilisateur.
+
+### 4.6 Pourquoi tests isoles via fixture `client` ?
+
+```python
+# tests/conftest.py
+@pytest_asyncio.fixture
+async def client(test_engine):
+    async def override_get_db():
+        async with TestSession() as session:
+            yield session
+    app.dependency_overrides[get_db] = override_get_db
+    async with AsyncClient(transport=ASGITransport(app=app), ...) as c:
+        yield c
+    app.dependency_overrides.clear()
+```
+
+Chaque test recoit une **SQLite in-memory toute fraiche** (avec `StaticPool`
+pour partager la meme connexion entre fixture et requete). La vraie `app.db`
+de dev n'est jamais touchee par pytest.
+
+---
+
+## 5. Decisions de conception : l'admin UI
+
+### 5.1 Auto-discovery via `Base.registry.mappers`
+
+Plutot que de demander aux utilisateurs de declarer leurs modeles dans
+l'admin (a la Django `admin.site.register()`), Fabrik **scanne dynamiquement
+SQLAlchemy** :
+
+```python
+def get_admin_models() -> dict:
+    return {m.class_.__tablename__: m.class_ for m in Base.registry.mappers}
+```
+
+Resultat : des qu'un module ajoute une classe heritant de `Base`, elle
+apparait dans la sidebar. Zero configuration.
+
+### 5.2 Formulaires generes par introspection des colonnes
+
+`col_input_type(col)` mappe les types SQLAlchemy vers des `<input type="...">` :
+
+| Type SQLAlchemy        | input HTML        |
+|------------------------|-------------------|
+| `Boolean`              | `checkbox`        |
+| `Integer`, `Numeric`   | `number`          |
+| `DateTime`             | `datetime-local`  |
+| `Date`                 | `date`            |
+| nom contient "email"   | `email`           |
+| nom == "password"      | `password`        |
+| presence de FK         | `select` (dropdown avec resolution display field) |
+| autre                  | `text`            |
+
+### 5.3 FK dropdowns intelligents
+
+Quand une colonne est une FK, l'admin :
+1. Detecte la table cible via `col.foreign_keys`
+2. Charge jusqu'a 500 lignes de la table cible
+3. Choisit la meilleure colonne d'affichage : `email` > `name` > `title` >
+   `label` > `username` > `id`
+4. Rend un `<select>` avec `<option value="{uuid}">email@example.com ({uuid_court})</option>`
+
+### 5.4 Multi-column search (v1)
+
+Recherche sans configuration : `?q=foo` -> ILIKE `%foo%` sur **toutes** les
+colonnes `varchar`/`string`/`text` (sauf `password`), combinees en `or_(...)`.
+
+### 5.5 Bulk delete (v1)
+
+Checkboxes par ligne + action bar sticky. La route `POST /admin/{table}/bulk-delete`
+recoit `ids[]` et execute `delete().where(Model.id.in_(ids))` -- **une seule
+requete SQL** pour N suppressions.
+
+### 5.6 CSV export (v1)
+
+`GET /admin/{table}/export.csv` -> `StreamingResponse` avec `csv.writer`.
+Nom de fichier : `{table}-{YYYY-MM-DD}.csv`. Toutes les colonnes sauf
+`password`.
+
+### 5.7 Responsive design
+
+Le CSS utilise un `@media (max-width: 768px)` qui transforme la sidebar en
+**drawer slide-in** avec hamburger + backdrop. Les `input` mobile sont en
+`font-size: 16px` pour empecher le zoom iOS au focus.
+
+---
+
+## 6. Background tasks : pourquoi ARQ
+
+### 6.1 Le besoin
+
+Toute application un peu serieuse a besoin de **deleguer des operations
+lentes** hors du cycle requete/reponse HTTP :
+- Envoi d'emails / notifications push
+- Ingestion / parsing de fichiers volumineux (PDFs, CSVs)
+- Calculs longs (rapports, exports, machine learning)
+- Appels d'API externes lents ou peu fiables (retry)
+
+Faire ces operations dans la route bloque le worker et timeout cote client.
+
+### 6.2 Pourquoi pas un worker Go ?
+
+Tentation classique : "Python est lent, mettons un worker en Go pour la
+performance." En realite, **95% des taches typiques sont I/O-bound** (attente
+API externe, requete DB, lecture disque). Sur ces operations, Python async
+= Go en performance, a la milliseconde pres.
+
+Le cout d'ajouter Go est massif :
+- Nouvelle toolchain (`go build`, `go mod`)
+- 2e langage a maintenir / debugger
+- 2e binaire / image Docker / pipeline de deploy
+- Communication inter-langage (queue ou cgo) avec sa propre complexite
+
+Reserve Go pour le 1% de cas ou tu as **vraiment** mesure que Python CPU
+est le bottleneck (parsing binaire intensif, math sur grands tenseurs).
+
+### 6.3 Pourquoi ARQ et pas Celery ?
+
+| | Celery | ARQ |
+|---|---|---|
+| Age | 2009 | 2017 |
+| Async natif | Non (sync, support async ajoute apres) | **Oui** |
+| Broker | RabbitMQ/Redis/etc. | Redis uniquement |
+| Taille code | Lourd | Leger (~3k lignes) |
+| Battle-tested | Instagram, Mozilla, Pinterest | Plus modeste |
+| Ecosysteme | Flower, beat, multiple plugins | Minimal |
+| Cohabitation FastAPI | Demande plomberie | Naturelle |
+
+ARQ est **conçu pour Python async** depuis le debut. Dans un projet ou
+**tout** est `async def` (routes, services, dependances), Celery introduit
+une rupture mentale (workers sync) ; ARQ reste coherent.
+
+Pour des cas de scale extreme (millions de jobs/jour, multi-broker, monitoring
+sophistique), Celery garde l'avantage. Pour 99% des projets, ARQ suffit
+largement.
+
+### 6.4 Architecture cote API
+
+Le pool Redis est cree dans le `lifespan` :
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # ... create_all tables ...
+    try:
+        app.state.arq_pool = await create_pool(RedisSettings.from_dsn(settings.REDIS_URL))
+    except Exception as e:
+        logger.warning("Redis indisponible (%s) -- background tasks desactives", e)
+        app.state.arq_pool = None
+    yield
+    if app.state.arq_pool is not None:
+        await app.state.arq_pool.close()
+```
+
+**Degradation gracieuse** : si Redis n'est pas joignable au demarrage, l'app
+demarre quand meme. Les routes qui veulent enqueue retournent 503 via la
+dependance `get_arq`. Le reste (admin, CRUD users, API) fonctionne sans
+difference.
+
+### 6.5 Architecture cote worker
+
+`worker.py` a la racine = entrypoint trivial qui appelle `run_worker(WorkerSettings)`.
+`WorkerSettings` vit dans `src/tasks.py` (a cote des taches qu'il execute) :
+
+- `functions: list` -> liste des fonctions appelables via `enqueue_job(name, ...)`
+- `redis_settings` -> connexion Redis (meme URL que cote API)
+- `max_jobs` -> concurrence par worker (10 par defaut)
+- `job_timeout` -> timeout par tache (5 min par defaut)
+
+Tu peux lancer N workers en parallele sur N machines : Redis joue le role
+de broker partage. C'est exactement le pattern Celery sans la lourdeur.
+
+---
+
+## 7. Le mecanisme `test-self`
+
+`cmd_test_self()` est la garantie que **Fabrik genere toujours un projet qui
+demarre vraiment**. Le workflow :
+
+1. `tempfile.mkdtemp()` -> projet jetable
+2. `cmd_new(absolute_path, no_input=True)` -> generation complete
+3. Verifications : venv existe, `.scaffold-version` ecrit, migration appliquee
+4. `subprocess pytest tests/ -q` -> doit retourner 0
+5. `subprocess uvicorn main:app --port <random>` en background
+6. Attente de l'ouverture du port (timeout 25s)
+7. HTTP GET sur `/`, `/admin/login`, `/docs` -> doit retourner 200
+8. Kill du serveur
+9. `cmd_add("articles")` -> test du module + auto-wiring
+10. `ast.parse()` sur les 5 fichiers generes -> doit etre du Python valide
+11. `shutil.rmtree(tmp)` (sauf si `--keep`)
+
+Le CI (`.github/workflows/ci.yml`) lance ce test a chaque push -- un commit
+qui casse la generation se voit immediatement.
+
+---
+
+## 8. Limites connues
+
+- **Pas de plugins externes.** Fabrik est volontairement monolithique. Le
+  jour ou tu veux brancher un module tiers (ex: OAuth Google), tu copies le
+  code dans `src/<module>/` au lieu de `pip install fabrik-plugin-X`.
+- **Python 3.13+ obligatoire.** On utilise les nouveautes (PEP 695, etc.) et
+  on ne supporte pas les versions plus anciennes.
+- **PostgreSQL recommande en prod.** SQLite marche pour le dev mais
+  manque de concurrence pour la production.
+- **L'admin scanne TOUS les modeles SQLAlchemy.** Pas (encore) de mecanisme
+  pour exclure des modeles internes.
+
+---
+
+## 9. Ressources
+
+- [README.md](README.md) : presentation generale
+- [docs/USAGE.md](docs/USAGE.md) : guide utilisateur complet
+- [scaffold.py](scaffold.py) : code source du moteur
+- [core/](core/) : templates copies dans chaque projet

fabrik_fastapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Falandy Jean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fabrik_fastapi-1.0.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# Inclut tous les fichiers de /core/ dans la distribution source (sdist).
+# Necessaire car setuptools n'inclut pas les non-Python par defaut.
+recursive-include fabrik/core *
+recursive-include fabrik/core/.* *
+
+# Dotfiles dans core/ (essentiels pour les projets generes)
+include fabrik/core/.gitignore
+include fabrik/core/.env.example
+include fabrik/core/.dockerignore
+include fabrik/core/alembic/versions/.gitkeep
+
+# Meta du repo (pour la sdist)
+include README.md
+include LICENSE
+include ARCHITECTURE.md
+include pyproject.toml
+include MANIFEST.in
+recursive-include docs *.md
+
+# Exclusions
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.bak
+global-exclude .DS_Store
+prune .github
+prune tests

fabrik_fastapi-1.0.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: fabrik-fastapi
+Version: 1.0.0
+Summary: Generateur de projet FastAPI async + opinionated (auth JWT, admin UI, ARQ, tests)
+Author-email: Falandy Jean <falandyjean@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FalandyJEAN/fabrik
+Project-URL: Repository, https://github.com/FalandyJEAN/fabrik
+Project-URL: Documentation, https://github.com/FalandyJEAN/fabrik/blob/main/docs/USAGE.md
+Project-URL: Issues, https://github.com/FalandyJEAN/fabrik/issues
+Project-URL: Changelog, https://github.com/FalandyJEAN/fabrik/releases
+Project-URL: Logo, https://raw.githubusercontent.com/FalandyJEAN/fabrik/main/docs/assets/logo.png
+Keywords: fastapi,scaffold,generator,boilerplate,async,sqlalchemy,alembic,admin,jwt,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Framework :: FastAPI
+Classifier: Environment :: Console
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Fabrik logo" width="200" />
+</p>
+
+<h1 align="center">Fabrik</h1>
+
+<p align="center">
+  <strong>Generateur de projet FastAPI async + opinionated.</strong><br>
+  En 60 secondes : auth JWT, admin UI auto-decouverte, tests isoles,<br>
+  background tasks (ARQ), migrations Alembic, CORS strict, responsive.
+</p>
+
+[![PyPI version](https://img.shields.io/pypi/v/fabrik-cli.svg)](https://pypi.org/project/fabrik-cli/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Fabrik CI](https://github.com/FalandyJEAN/fabrik/actions/workflows/ci.yml/badge.svg)](https://github.com/FalandyJEAN/fabrik/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Version :** `1.0.0` &nbsp;&middot;&nbsp; **Auteur :** Falandy Jean &nbsp;&middot;&nbsp; **Licence :** MIT
+
+---
+
+## Installation
+
+```bash
+pip install fabrik-cli
+```
+
+Verifier l'installation :
+
+```bash
+fabrik --help
+```
+
+Pre-requis : **Python 3.13+**.
+
+---
+
+## 60 secondes pour demarrer
+
+```bash
+fabrik new mon-api
+cd mon-api
+venv\Scripts\activate                 # Windows
+# source venv/bin/activate            # Linux/Mac
+python create_superuser.py
+python -m uvicorn main:app --reload
+```
+
+Ouvre :
+- **Admin UI** : http://127.0.0.1:8000/admin
+- **Swagger** : http://127.0.0.1:8000/docs
+
+---
+
+## Ce que tu obtiens out-of-the-box
+
+| Domaine            | Choix par defaut                                              |
+|--------------------|---------------------------------------------------------------|
+| Framework          | FastAPI 0.136 + Starlette                                     |
+| ORM                | SQLAlchemy 2.0 **async** (`AsyncSession`)                     |
+| Driver DB          | `aiosqlite` (dev) / `asyncpg` (prod PostgreSQL)               |
+| Auth               | JWT (access + refresh) avec bcrypt                            |
+| Admin              | UI auto-decouverte responsive, multi-search, bulk delete, CSV |
+| Migrations         | Alembic (autogenerate)                                        |
+| Background tasks   | ARQ (Redis-backed, async-native) avec degradation gracieuse   |
+| Tests              | pytest + pytest-asyncio + DB SQLite in-memory isolee          |
+| CORS               | Strict via `BACKEND_CORS_ORIGINS` (pas de `*`)                |
+| Config             | `pydantic-settings` (12-factor)                               |
+| Docker             | `Dockerfile` Python 3.13-slim + `docker-compose.yml`          |
+
+---
+
+## Les 4 commandes
+
+| Commande                            | Effet                                                         |
+|-------------------------------------|---------------------------------------------------------------|
+| `fabrik new <nom>`                  | Genere un projet complet (venv + deps + migration initiale)   |
+| `fabrik add <module>`               | Ajoute un module CRUD (auto-wire + migration + tests)         |
+| `fabrik upgrade`                    | Met a jour un projet existant a la derniere version           |
+| `fabrik test-self`                  | Meta-test : verifie que le scaffold genere un projet OK       |
+
+Detail complet dans [docs/USAGE.md](docs/USAGE.md).
+
+---
+
+## Pourquoi Fabrik ?
+
+Fabrik couvre l'angle mort entre **Django** (rigide, monolithique, sync) et
+**FastAPI nu** (zero opinion, 2 jours de plomberie a chaque projet).
+
+| | FastAPI standard | Django | **Fabrik** |
+|---|---|---|---|
+| Stack async | oui | non | **oui** |
+| Auth JWT prete | non | tierce | **oui** |
+| Admin UI auto-genere | non | oui (sync) | **oui (async, responsive)** |
+| Background tasks | non | Celery (tiers) | **oui (ARQ inclus)** |
+| Tests isoles fournis | non | oui | **oui** |
+| Architecture modulaire | a faire | apps | **`src/<module>/`** |
+| Migration de projet | non | manuel | **`fabrik upgrade`** |
+| Demarrage zero-config | 2j | 30 min | **60 secondes**          |
+
+Detail des choix de conception : [ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## Structure d'un projet genere
+
+```
+mon-api/
+├── main.py                       FastAPI app + lifespan + pool ARQ
+├── worker.py                     Entrypoint ARQ (python worker.py)
+├── docker-compose.yml            Redis + (PostgreSQL optionnel)
+├── .env                          SECRET_KEY 256 bits + CORS + DB + Redis
+├── .scaffold-version             Trace de la version Fabrik (pour upgrade)
+├── create_superuser.py
+├── requirements.txt
+├── pytest.ini
+├── alembic.ini + alembic/
+├── src/
+│   ├── database.py               AsyncEngine + get_db
+│   ├── tasks.py                  ARQ tasks + WorkerSettings + get_arq dep
+│   ├── core/                     Config, security, mixins, pagination
+│   ├── users/                    Module exemple (models/schemas/service/router)
+│   └── admin/                    UI auto-decouverte (router + templates + static)
+└── tests/
+    ├── conftest.py               Fixtures async (DB in-memory isolee)
+    ├── test_users.py
+    └── test_tasks.py
+```
+
+---
+
+## Architecture du repo Fabrik
+
+```
+fabrik/                           Repo GitHub
+├── pyproject.toml                Package metadata (PyPI)
+├── MANIFEST.in
+├── README.md, ARCHITECTURE.md, LICENSE
+├── docs/
+│   ├── USAGE.md                  Guide utilisateur
+│   └── PUBLISHING.md             Workflow de release PyPI
+├── .github/workflows/ci.yml      CI : lance test-self a chaque commit
+└── fabrik/                       Package Python
+    ├── __init__.py
+    ├── __main__.py               Pour `python -m fabrik`
+    ├── scaffold.py               Moteur CLI
+    └── core/                     Templates copies a chaque `new`
+```
+
+---
+
+## Developpement local
+
+Si tu veux contribuer ou tester en local sans publier sur PyPI :
+
+```bash
+git clone https://github.com/FalandyJEAN/fabrik.git
+cd fabrik
+pip install -e .                  # installation en mode editable
+fabrik test-self                  # verifie que tout fonctionne
+```
+
+Tout changement qui modifie la structure des projets generes doit :
+
+1. Bumper `SCAFFOLD_VERSION` dans `fabrik/scaffold.py` (et `version` dans `pyproject.toml`)
+2. Ajouter une fonction `patch_vN_to_vM(root)` **idempotente**
+3. L'enregistrer dans `PATCHES`
+4. `fabrik test-self` doit passer en local et en CI
+
+---
+
+## Publication PyPI
+
+Workflow complet dans [docs/PUBLISHING.md](docs/PUBLISHING.md). En resume :
+
+```bash
+pip install -e ".[dev]"
+python -m build
+twine upload dist/*
+```
+
+---
+
+## Licence
+
+MIT &copy; 2026 Falandy Jean &mdash; voir [LICENSE](LICENSE).