MIC

An explicit architecture for robust, testable, framework-agnostic Python and Node.js services.

MIC (Model / Interface / Controller) separates domain behavior, its interfaces, and the adapters that expose it. Two official implementations use that contract: mic-python, with three PyPI distributions and a cookiecutter scaffold, and mic-node, with fifteen TypeScript npm packages and a service generator.

Start with Python Start with Node.js Understand MIC

Why you are here

• You want robust services

  ---

  Strict contracts (Pydantic v2 extra="forbid", frozen models, revalidated updates), a clear boundary between domain logic and HTTP, and API errors with canonical codes. No more "works in dev, breaks in prod".

  Principles

• You want framework independence

  ---

  A MIC route can be served by FastAPI or Litestar in Python, and by Node HTTP, Express, Fastify, Hono, or NestJS in TypeScript. Domain handlers do not change.

  Architecture

• You want executable evidence

  ---

  The Python gate requires 100% coverage. Node releases install the published archives in an empty project and run the generated service. Validation limits are documented without extrapolation.

  Mirror tests

• You want a new service in 30 minutes

  ---

  cookiecutter generates the Python service; @mic-struct/create-mic-service generates the Node.js service. Both include operational routes, an example module, and the corresponding tests.

  Scaffold Node.js

Python in 30 seconds

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,
    ),
)))

The same HttpRouteSpec can also be served by build_litestar_router(...) - domain code does not change. That is MIC.

Node.js / TypeScript in 30 seconds

All fifteen @mic-struct packages are published on the public npm registry and require no token. Generate and verify the service:

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

The generated project exposes liveness, readiness, and its OpenAPI 3.1 contract. The Node.js quickstart provides the exact package list and publication guarantees.

What is shipped

Python

Python imports always use mic.<module>; the Package column tells you which PyPI distribution provides each module. See Package organization.

Module	Package	Role
mic.contracts	mic-core	Static StrictSchema or governed SchemaRegistry, with strict HTTP envelopes
mic.model	mic-core	DomainError, TransientError, NotFoundError and canonical 4xx / 5xx mapping
mic.http	mic-core	Framework-neutral HttpRouteSpec plus FastAPI and Litestar adapters
mic.auth	mic-core	Audience-bound service tokens with rotation and exact scopes
mic.tenancy	mic-core	Organization context plus a relational view that rejects unscoped access
mic.client	mic-core	Auto-signed ServiceHttpClient with canonical error mapping
mic.observability	mic-core	JSON configure_logging() plus Prometheus counters, gauges and histograms
mic.datastorage	mic-datastore	SqlDataStorage, document / graph / key-value variants, sessions and idempotent prepare()
mic.outbox	mic-datastore	At-least-once delivery with optional per-aggregate ordering
mic.scheduling	mic-datastore	Periodic work with locking, checkpoints, tracking, and silence detection
mic.ratelimit	mic-platform	RateLimiter + RateLimitMiddleware with in-memory or Redis backends
template/	(repo mic-struct)	Cookiecutter scaffold for a complete service

Node.js / TypeScript

Group	Role
@mic-struct/mic-core, @mic-struct/mic-client	Contracts, errors, HTTP, authentication, and service calls
@mic-struct/mic-datastore, @mic-struct/mic-redis	Persistence, cache, outbox, queues, realtime, and scheduling
HTTP adapters	Node HTTP, Express, Fastify, Hono, and NestJS
@mic-struct/mic-observability, @mic-struct/mic-resilience	Logs, traces, metrics, Sentry, and circuit breakers
@mic-struct/create-mic-service	Generator for a tested service with OpenAPI and an operator CLI

The Node implementation contains fifteen packages versioned together. They require Node.js 24 or later.

Built for confident delivery

• PyPI: mic-core, mic-datastore, mic-platform - installable from anywhere
• npm: fifteen @mic-struct packages - published on the public registry, requiring no authentication, and tested after publication
• MIT - usable in commercial, open-source, and proprietary contexts
• Python 3.14 - an explicit adoption choice that requires a recent runtime
• Node.js 24+ - declared by every published package
• Validated on real services - integration-heavy workloads; complex aggregates and billion-row scale remain to be proven
• Documented scope and exit - limits, maturity, and reversibility