specstar 0.11.0

Spec-driven backend platform for FastAPI: REST + GraphQL + search + version history + admin UI from a single msgspec.Struct

Spec-driven backend platform for FastAPI
Generate REST APIs, GraphQL, search, version history, and an admin UI from a single Python model.

Renamed from autocrud to specstar (v0.10.0). The old name still installs as a deprecation shim that redirects every autocrud[.X] import to specstar[.X]. New projects should pip install specstar. See the migration guide.

v0.11 adds spec-driven authoring (additive, zero breaking changes). Edit a single spec.md in prose; a Claude Code skill or the specstar gen CLI translates it into the declarative Python the engine consumes. See the Spec-Driven Authoring guide and the v0.11 upgrade notes.

Focus on business logic, not infrastructure.

⭐ If you find this project useful, consider giving it a star.

---

Why SpecStar

Modern backend development repeatedly rebuilds the same infrastructure:

• CRUD APIs
• validation
• search and filtering
• version history
• permissions
• background jobs
• admin tools

Most of this code is not business logic.

SpecStar eliminates this repetition by using a spec-driven architecture.

Define your model once, and the framework generates the rest.

What sets SpecStar apart

Most "model → API" generators stop at routes. SpecStar treats every resource as a versioned timeline by default: updates create revisions, history stays queryable, and rollback is built in. Don't need history? Ignore it — the same routes work as plain CRUD.

---

Example

Define a resource model:

from msgspec import Struct

class User(Struct):
    name: str
    email: str

Register the model:

from fastapi import FastAPI
from specstar import spec

app = FastAPI()

spec.add_model(User)
spec.apply(app)

Start the server:

uvicorn main:app

Optional startup tuning:

export SPECSTAR_DEFAULT_QUERY_LIMIT=1000

This controls the default page size for list endpoints. Per-request limit still overrides it.

You now automatically get:

POST   /users
GET    /users
GET    /users/{id}
PUT    /users/{id}
PATCH  /users/{id}
DELETE /users/{id}

OpenAPI documentation is generated automatically.

---

Architecture

graph TD

FastAPI --> SpecStar
SpecStar --> ResourceManager
ResourceManager --> Storage

Storage --> MetaStore
Storage --> RevisionStore
Storage --> BlobStore

SpecStar --> REST_API
SpecStar --> GraphQL_API
SpecStar --> UI_Generator

---

Core Features

Spec-driven APIs

SpecStar generates APIs directly from Python models.

Model
  ↓
REST API
GraphQL API
OpenAPI

---

Versioned resources

Every resource maintains immutable revision history.

Resource
 ├── r1
 ├── r2
 └── r3

Advantages:

• audit history
• rollback
• draft workflows
• debugging

---

Built-in search

Search operates on indexed metadata instead of scanning full resource payloads.

QueryBuilder
   ↓
ResourceManager.search()
   ↓
MetaStore.search()

---

Background jobs

Jobs are modeled as resources.

create()
  ↓
message_queue.put(resource_id)

Workers process jobs through:

ResourceManager.start_consume()

---

Storage abstraction

SpecStar supports multiple storage backends.

Backend	Meta	Revision	Blob
Memory	memory	memory	memory
Disk	SQLite	files	filesystem
S3	SQLite	S3	S3
Postgres	PostgreSQL	S3	S3

You can also implement custom storage systems.

---

UI generation

SpecStar can generate a web interface directly from the API.

API
 ↓
UI generator
 ↓
admin dashboard

This allows rapid creation of internal tools.

---

Comparison

Feature	SpecStar	Hasura	Django
REST API	✅	❌	✅
GraphQL	✅	✅	⚠️
Version history	✅	❌	❌
Search engine	✅	SQL	ORM
Storage	pluggable	PostgreSQL	relational
Background jobs	built-in	external	external
UI generation	✅	console	admin

---

Quickstart

Install:

pip install specstar

Spec-driven (v0.11+) — bootstrap a starter project, then describe resources in prose:

specstar init my_app
# edit spec.md, then in Claude Code:
/specstar regen
# CI-friendly drift check (no LLM):
specstar verify

See the Spec-Driven Authoring guide for the full workflow.

Classic Python — register models directly:

Run your app:

uvicorn main:app

Open:

http://localhost:8000/docs

---

Documentation

Full documentation:

https://hychou0515.github.io/specstar/

---

Example use cases

SpecStar works well for:

• internal tools
• content systems
• configuration management
• job processing systems
• administrative APIs
• workflow management systems

---

License

MIT