Documentation · JFastFramework

Start here

Quickstart

Generate the backend nobody wants to write twice, and keep it from decaying while a team — or an agent — works on it.

Running it locally

JFastFramework is on PyPI as a pre-release. pip install jfastframework is enough to use it; install from a checkout when you intend to change the framework itself.

Containers up and waited for, migrations applied, then the API, the queue worker and the frontend together. One command for the things somebody does every morning, in the order that makes the failures land where they belong.

Architecture

Every decision here has a cost. This document names both sides.

Build

Modules and layouts

Two levels of generation:

Contracts

AGENTS.md says what to do. A contract says what is allowed, and something checks it.

Inspect and analyze

check is one line of a pipeline, not the pipeline. It runs no linter, no type checker and no test suite — see What check does not check.

Shared code and events

Two features, one idea: coupling that is easy to add, invisible once added, and expensive to remove after a second person has copied the pattern. Both are therefore checked rather than agreed.

Datastores

Every datastore is a plugin. Enable what the service needs, and the client, the health check and the container all arrive together.

RAG and vector search

Ingest documents, find the passages that answer a question, hand them to a model with citations. The rag plugin does the retrieval half; the llm plugin does the answering half and pays for the embeddings.

Language models

Chat, structured output, vision and embeddings over any OpenAI-compatible API, behind a spending cap that holds across workers.

Transactions

When a request's writes are committed, what a failed write turns into, and how two requests that race for the same row are kept from both winning.

Queues and events

Two different things, deliberately two different plugins -- and, between the modules of one service, a third thing built on the first: local domain events, which need no broker.

Calling other services

jfastframework.http is the client a service uses to call its siblings. It exists so that each service does not write its own, and so that the four things every hand-written one gets wrong are decided once: how long to wait, what to retry, when to stop calling an upstream that is down, and how many calls to let pile up behind a slow one.

Frontends

Two ways to put a UI in front of a JFast backend. Pick by whether you want a build step.

Packages

Nothing in this catalogue is installed by default. A service that serves JSON should not carry numpy — and the moment it does, the plugin graph stops describing what the service actually needs, which is the property that makes the graph worth having.

Writing a plugin

A plugin is a class with metadata and up to five optional hooks. Nothing else.

Run

Workspaces

A single service needs no workspace. The moment there are two, three questions appear that per-service config cannot answer:

Deployment

Deployment artifacts are generated from the plugin graph, not maintained by hand. Disable a plugin and its container disappears from the next generated compose file. That is the whole idea: infrastructure cannot drift away from what the application actually loads.

Telemetry

Logs tell you what one service did; metrics tell you how often. Neither follows one request through the API, its SQL, a model call, a second service and the job it queued -- which is the first thing you need when something is slow in production. The telemetry plugin does that with OpenTelemetry traces, exported over OTLP to anything that speaks it: Jaeger, Grafana Tempo, Honeycomb, Datadog, an OpenTelemetry Collector.

Kubernetes

jfast init asks whether you need it and writes the tree if you say yes.

Resilience

What a service does when something it depends on stops answering: how long it waits, whether it retries, when it stops asking, what the client gets, and what /ready says. All of it is on by default. This page lists the numbers, the reasons for them, and the drills that check them against real servers.

Scaling

Every claim about capacity on this page is a number from a run, with the machine, the sizes and the method next to it. Where a number would only be a guess, the page says so instead.

Cloud

Three things a service reaches for once it leaves your laptop: configuration it cannot keep in a file, a way to run something without a server, and a way to reach a phone.

Migrations and tests

Both are wired into every generated service. Neither is something you set up.

Time zones

Storage was settled in 0.1.0a4: UTCDateTime writes UTC, reads back UTC, and refuses a naive datetime on write. This page is about the other half — computing with those values — which is where a multi-region deployment actually goes wrong.

Guard

Authentication

JWT verification, scopes, key rotation and revocation.

Accounts

Users, password login, roles and permissions -- the user store the auth plugin deliberately leaves out, as a plugin you turn on.

Encryption

Some secrets a service holds are its users' data, and it has to read them back: the password that opens a customer's e-signature key, a token for their bank. A hash does not work -- the value is needed in the clear to use it -- and SecretStr only keeps a value out of logs; the database still holds the plain text. jfastframework.encryption is for those.

Rate limiting

A login endpoint with no rate limit is a credential-stuffing target. This plugin is the limit, and it lives in the application rather than at the edge.

Storage

Files live on a named disk. Your code writes to "public" or "invoices"; whether that disk is a directory, an S3 bucket or a MinIO container is configuration. The same handler works in development and in production without an edit.

Multi-tenancy

One deployment, many customers, each seeing only their own data.

Websockets

A message is addressed to a person, not to a socket. Which worker happens to hold that person's connection is not something your code should know.

Polyglot services

A JFast service is not "a service written with JFast". It is a service that satisfies this contract. That distinction is the whole reason a Go service and a Python service can sit behind the same gateway, take ports from the same workspace, and be fronted by the same Caddyfile — none of which know or care which language produced them.

Working with AI agents

The premise of this framework is that an agent writing code in your repository is now normal, and that the thing which makes it survivable is not a better prompt — it is rules the agent cannot quietly break.

Skills for agents

A skill is a folder with a SKILL.md: instructions for one task, written so an agent can execute it without reconstructing context from the source tree.

Project

Maturity

One version number cannot describe this repository honestly. The kernel is tested, typed and exercised by CI on every push; the Kafka client has never spoken to a broker. Calling both "0.7.0" told a reader nothing, which is why the package restarts at 0.1.0a1 and why maturity is tracked here, per subsystem, instead.