MIC

Une architecture explicite pour des services Python et Node.js solides, testables et agnostiques au framework.

MIC (Model / Interface / Controller) sépare le métier, ses interfaces et les adaptateurs qui l'exposent. Deux implémentations officielles appliquent ce contrat : mic-python, avec trois distributions PyPI et un scaffold cookiecutter, et mic-node, avec quinze paquets npm TypeScript et un générateur de service.

Démarrer avec Python Démarrer avec Node.js Comprendre MIC

Pourquoi vous êtes ici

• Vous voulez des services robustes

  ---

  Des contrats stricts (Pydantic v2 extra="forbid", frozen, ré-validés), une frontière claire entre métier et HTTP, des erreurs d'API avec un code canonique. Pas de "ça marche en dev mais pas en prod".

  Principes

• Vous voulez du framework-agnostique

  ---

  Une route MIC peut être servie par FastAPI ou Litestar en Python, et par Node HTTP, Express, Fastify, Hono ou NestJS en TypeScript. Le gestionnaire métier ne change pas.

  Architecture

• Vous voulez des preuves exécutables

  ---

  Le contrôle Python exige 100 % de couverture. Les versions Node vérifient les archives publiées dans un projet vierge et exécutent le service généré. Les limites de validation sont publiées sans extrapolation.

  Tests miroir

• Vous voulez un nouveau service en 30 minutes

  ---

  cookiecutter génère le service Python ; @mic-struct/create-mic-service génère le service Node.js. Les deux livrent les routes d'exploitation, un module exemple et les tests associés.

  Scaffold Node.js

Python en 30 secondes

pip install "mic-core[fastapi]"

from fastapi import FastAPI
from mic.contracts import StrictSchema, wrap_http_success
from mic.http import HttpResponseSpec, HttpRouteSpec
from mic.fastapi import build_fastapi_router


class CreateItem(StrictSchema):
    name: str
    quantity: int = 0


def _create(*, payload: CreateItem) -> HttpResponseSpec:
    return HttpResponseSpec(
        status_code=201,
        body=wrap_http_success({"name": payload.name, "qty": payload.quantity}),
    )


app = FastAPI()
app.include_router(build_fastapi_router(routes=(
    HttpRouteSpec(
        method="POST", path="/api/v1/items",
        name="items_v1_create", category="items",
        handler=_create,
    ),
)))

HttpRouteSpec est aussi servi par build_litestar_router(...) — le code métier ne change pas. C'est ça, MIC.

Node.js / TypeScript en 30 secondes

Les quinze paquets @mic-struct sont publiés sur le registre public npm et ne demandent aucun jeton. Générez puis vérifiez le service :

pnpm dlx @mic-struct/create-mic-service ./my-service
cd my-service
pnpm install
pnpm verify
pnpm start

Le projet obtenu expose sa santé, son état de préparation et son contrat OpenAPI 3.1. Le quickstart Node.js donne la liste exacte des paquets et les garanties de publication.

Ce qui est livré

Python

Les imports Python sont toujours mic.<module> ; la colonne Paquet indique quelle distribution PyPI le fournit (cf. Organisation des paquets).

Module	Paquet	Rôle
mic.contracts	mic-core	StrictSchema statique ou SchemaRegistry gouverné, enveloppes HTTP strictes
mic.model	mic-core	DomainError, TransientError, NotFoundError… (mappées 4xx / 5xx canoniquement)
mic.http	mic-core	HttpRouteSpec agnostique + adaptateurs FastAPI et Litestar (parité prouvée)
mic.auth	mic-core	Jetons inter-service liés à l'audience, rotation et portées exactes
mic.tenancy	mic-core	Contexte d'organisation + vue relationnelle qui refuse les accès hors portée
mic.client	mic-core	ServiceHttpClient httpx auto-signé + mapping erreurs canonique
mic.observability	mic-core	configure_logging() JSON + Prometheus counter / gauge / histogram
mic.datastorage	mic-datastore	SqlDataStorage (+ document / graph / clé-valeur), sessions, prepare() idempotent
mic.outbox	mic-datastore	Livraison at-least-once avec ordre par agrégat optionnel
mic.scheduling	mic-datastore	Tâches périodiques avec verrou, point de reprise, suivi et alerte de silence
mic.ratelimit	mic-platform	RateLimiter + RateLimitMiddleware (in-memory / Redis)
template/	(repo mic-struct)	Cookiecutter — répondez à 3 questions, obtenez un service complet

Node.js / TypeScript

Groupe	Rôle
@mic-struct/mic-core, @mic-struct/mic-client	Contrats, erreurs, HTTP, authentification et appels inter-services
@mic-struct/mic-datastore, @mic-struct/mic-redis	Persistance, cache, outbox, files, temps réel et planification
Adaptateurs HTTP	Node HTTP, Express, Fastify, Hono et NestJS
@mic-struct/mic-observability, @mic-struct/mic-resilience	Journaux, traces, métriques, Sentry et disjoncteurs applicatifs
@mic-struct/create-mic-service	Générateur d'un service testé avec OpenAPI et CLI opérateur

L'implémentation Node compte quinze paquets versionnés ensemble. Ils exigent Node.js 24 ou une version ultérieure.

Fait pour livrer en confiance

• PyPI : mic-core · mic-datastore · mic-platform — installables depuis n'importe où
• npm : quinze paquets @mic-struct — publiés sur le registre public, sans authentification, et testés après publication
• MIT — utilisable en commercial / open-source / propriétaire
• Python 3.14 — choix assumé qui impose un runtime récent
• Node.js 24+ — contrat déclaré dans chaque paquet publié
• Services réels validés — forte densité d'intégration ; les agrégats complexes et l'échelle milliard restent à éprouver
• Périmètre et sortie documentés — limites, maturité et réversibilité