python-server-starter

A production-grade, enterprise-ready cloud-native Python / FastAPI microservice scaffold — the Python counterpart to binrchq/go-starter.

---

📚 Complete Documentation & Reading Series

Category	Documentation / Guide	Description
🚀 Hands-On Tutorial	docs/tutorial.md	Step-by-step walkthrough to build, extend, and deploy features from scratch
Routing Architecture	ROUTERS.md	Multi-port routing matrix (outer, inner, admin, openapi, metrics), CORS, and wrapper policies
Sub-layer Routing	app/core/routers/README.md	Router layer organization, middleware chaining, and route group registration
API & Controllers	app/core/api/v1/controllers/README.md	Standard RESTful controller conventions and layer separation
Business Domain	app/core/biz/README.md	Domain logic, verification services, external integrations
External Services	app/core/biz/external/ARCHITECTURE.md	Third-party vendor integration architecture, timeout, and retry guidelines
State & Coordination	app/core/preparer/state/README.md	Pluggable distributed coordination (StateAdapter), etcd and in-memory locks
Traditional Services	app/core/service/tradi/README.md	Stateless multi-port HTTP listeners and Prometheus metrics services
Developer Skills & Recipes	skills/README.md	Rapid code generation recipes (models, controllers, routers, services, adapters)

---

🌟 Key Features

• Multi-Port Routing Architecture: Strict separation of concern across outer (public), inner (service RPC), admin (management), openapi (partners), and metrics (Prometheus) listeners — each with its own FastAPI app and policy.
• Multi-Driver Database Support: Async SQLAlchemy 2.0 with PostgreSQL (asyncpg), MySQL (aiomysql), and SQLite (aiosqlite, automatic WAL mode).
• Enterprise Migration Engine: Timestamped SQL migration pairs, per-dialect directories, dirty-state tracking, safety-guarded rollback, and a force repair command.
• Dynamic Table Sharding & Pre-creation: ShardableMixin plus a TablePreparer daemon that provisions next month's sharded tables in advance.
• High-Performance Timer Wheel: heapq-based scheduled execution with DAG dependency chaining, per-task concurrency limits, preconditions, and completion hooks.
• Declarative Dependency Injection: A type-driven Container / ProviderSet implementation inspired by Google Wire.
• Microservice State & Coordination: Pluggable StateAdapter with etcd leases/locks and an in-memory fallback.
• Structured Observability: structlog JSON/console logging and a Prometheus registry with service-status and HTTP metrics.

---

🏗️ Architecture Overview

python-server-starter/
├── app/
│   ├── main.py                  # Module entrypoint
│   ├── cli/                     # Typer CLI (serve, migrate, version)
│   ├── configs/                 # pydantic-settings models + config.yaml
│   ├── serve/                   # Container (DI) + Serve lifecycle (loooop)
│   └── core/
│       ├── api/
│       │   ├── middleware/      # CORS, request logger, recovery, public marker
│       │   └── v1/controllers/  # Layered controllers (outer/inner/admin/openapi/common)
│       ├── biz/                 # Domain logic, verification, external integrations
│       ├── infra/
│       │   ├── migrate/         # Multi-driver migration engine
│       │   ├── redis/           # Redis connection adapter
│       │   └── metrics/         # Prometheus registry + middleware
│       ├── model/               # SQLAlchemy bases, mixins, sharding, registry
│       ├── preparer/            # Unified dependency container
│       │   ├── database/        # Async engine + TablePreparer
│       │   ├── cache/           # Memory & Redis cache adapters
│       │   ├── messaging/       # Kafka, RabbitMQ, Redis Pub/Sub
│       │   ├── state/           # etcd & memory state adapters
│       │   └── logger/          # structlog configuration
│       ├── routers/             # Routing layer (v1/outer, v1/inner, v1/admin, v1/openapi)
│       └── service/             # ServiceManager, TimerWheel, tradi + distr services
├── migrations/                  # Versioned SQL migration scripts (postgres/mysql/sqlite)
├── skills/                      # Rapid code generation recipes
└── tests/                       # pytest suite

---

🚀 Quick Start

1. Prerequisites

• Python 3.11+ (3.12/3.13 recommended)
• Docker & Docker Compose (optional)
• PostgreSQL / MySQL / SQLite (SQLite needs zero setup)

2. Install

make venv install      # or: python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"

3. Run Database Migrations

python -m app migrate up

4. Start the Application

python -m app serve

Verify:

curl http://localhost:8000/health
curl http://localhost:8000/api/public/ping
curl http://localhost:8001/api/system/services
curl http://localhost:9090/metrics

---

⚙️ Configuration Reference

environment: dev

server:
  host: 0.0.0.0
  port: 8000          # Outer router (default client entry)
  admin_port: 8001    # Admin router (0 to disable)
  internal_port: 8002 # Inner router (0 to disable)
  openapi_port: 8003  # OpenAPI router (0 to disable)
  metrics_port: 9090  # Metrics router (0 to disable)

database:
  driver: sqlite      # postgres | mysql | sqlite
  name: app.db

redis:
  host: localhost
  port: 6379

logging:
  level: info
  format: json
  output: stdout

Any value can be overridden with a SECTION__FIELD environment variable (e.g. SERVER__PORT=9000, DATABASE__DRIVER=postgres) or a serve flag.

---

🧪 Testing

make test          # pytest
make lint          # ruff

---

🐳 Docker

make docker-build
make compose-up    # spins up postgres, mysql, redis, rabbitmq, kafka, etcd

---

License

MIT © 2026 BINRC