spaps-server-quickstart 0.5.0

Shared FastAPI/Celery scaffolding for Sweet Potato service backends.

SPAPS Server Quickstart

Reusable FastAPI, SQLAlchemy, Celery, auth, and operational scaffolding for Sweet Potato service backends. This is the active backend package in the repository and the shared foundation for SPAPS-aligned Python services.

pip install spaps-server-quickstart

TL;DR

The Problem: new FastAPI services keep re-solving the same problems around app factories, auth middleware, RBAC, async database wiring, Celery bootstrapping, and deployment guardrails.

The Solution: spaps-server-quickstart packages the shared SPAPS backend conventions into one installable Python package so new services start from a tested baseline instead of ad hoc scaffolding.

Why Use spaps-server-quickstart?

Feature	What it gives you
App factory and startup checks	create_app, settings loaders, and environment validation
Shared auth + RBAC	SPAPS auth middleware, auth channels, trusted-service middleware, and role dependencies
Async data layer	SQLAlchemy 2.0 async helpers, migration runner, and session dependencies
Operational templates	Deployment scripts, compose stubs, dev DB helpers, and packaging patterns

Metadata

• package_name: spaps-server-quickstart
• latest_version: 0.4.0
• minimum_runtime: Python >=3.12
• api_base_url: https://api.sweetpotato.dev

Quick Start

from fastapi import APIRouter

from spaps_server_quickstart import create_app
from spaps_server_quickstart.settings import BaseServiceSettings


def load_settings() -> BaseServiceSettings:
    return BaseServiceSettings(env="test", app_name="README Quickstart")


router = APIRouter()


@router.get("/hello")
async def hello() -> dict[str, str]:
    return {"message": "Hello from SPAPS"}


app = create_app(settings_loader=load_settings, api_router=router)

Design Principles

1. Start from a real service baseline, not a toy template.
2. Keep auth, middleware, and operational guardrails reusable across services.
3. Prefer explicit service composition through settings loaders and dependency injection.
4. Keep the local-development path close to production behavior.
5. Make the happy path easy without hiding the underlying FastAPI and SQLAlchemy primitives.

What the Package Includes

Area	Highlights
App lifecycle	create_app, startup checks, environment validation, logging
Auth	SpapsAuthMiddleware, auth cookies, auth channel service, local auth mode
Routing and RBAC	Base router builder, role helpers, authenticated-user dependencies
Database	Async sessionmaker factory, migration runner, Alembic helpers
Tasks	Celery app factory plus notification and ping task helpers
Service SDK helpers	Admin token cache, server-side SPAPS clients, feature evaluation, trusted-service middleware
Templates	Domain examples, operations bundle, env examples, and local dev helpers

Local Development Mode

Set DEVELOPMENT_ENVIRONMENT=local to enable the local-auth bypass workflow used in development and tests.

from spaps_server_quickstart.local_mode import (
    LocalAuthMiddleware,
    get_default_registry,
)
from spaps_server_quickstart.settings import BaseServiceSettings

settings = BaseServiceSettings(development_environment="local")

if settings.is_local_development:
    app.add_middleware(LocalAuthMiddleware, registry=get_default_registry())

Default personas:

Persona	Token	Roles
Admin	local-admin	admin, user
User	local-user	user

Configuration

Key settings exposed through BaseServiceSettings and related SPAPS settings:

Setting	Purpose
development_environment	Enables local bypass mode when set to local
spaps_auth_exempt_paths	Comma-separated paths that skip SPAPS auth
cors_allow_origins	Shared CORS configuration
secure_messages_enabled	Toggles secure-messaging gateway support
secure_messages_timeout	HTTP timeout for secure-messaging calls

Example environment:

DEVELOPMENT_ENVIRONMENT=local
SPAPS_AUTH_EXEMPT_PATHS=/health,/docs
CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:5173

Operational Templates

The package ships with templates and scripts for the workflows the real SPAPS services use:

• Docker Compose and reverse-proxy stubs
• Deploy scripts with preflight and post-deploy checks
• Database backup, restore, and migration helpers
• Shared dev DB helpers and local debug-loop support
• Example domains and tests for bootstrapping new services

Architecture

FastAPI service
  |
  +--> create_app + settings loader
  |
  +--> auth middleware / RBAC / dependencies
  |
  +--> async DB session + Alembic helpers
  |
  +--> Celery tasks + service SDK helpers
  |
  +--> shared operational templates
          |
          v
    SPAPS-aligned production service

Validation and Development

When working in this repository, the root Makefile is the canonical workflow:

make install
make pytest
make lint
make typecheck
make test
make local-up

Useful additional commands:

make pytest-full
make pytest-cov
make migrate
make new-migration MSG="add_example_table"

Troubleshooting

make pytest reports no affected tests

That is expected when testmon sees no impacted tests. Use make pytest-full when you need a full run.

Local auth bypass is not active

Confirm DEVELOPMENT_ENVIRONMENT=local is set before application startup.

Unauthenticated routes still require auth

Check spaps_auth_exempt_paths and make sure the configured paths match the actual router paths.

Startup fails on environment validation

Review the required settings and any environment-safety checks triggered during startup validation.

I need a new service quickly

Start from the included templates and keep the repo-root validation path intact while adapting the service-specific settings.

Limitations

• This package is a scaffold, not a complete application by itself.
• Downstream services still need their own domain routers, schemas, repositories, and deployment configuration.
• Some operational templates intentionally require environment-specific edits before production use.

FAQ

Is this the active SPAPS backend in this repo?

Yes. This package replaces the old Node/Express stack as the active backend surface.

Does it include local auth bypass support?

Yes. Set DEVELOPMENT_ENVIRONMENT=local and wire in the local-mode helpers.

Can I use it without Celery?

Yes. Celery helpers are included, but you can compose only the pieces your service needs.

Does it include RBAC helpers?

Yes. Use require_roles, has_required_roles, and the authenticated-user dependencies.

What is the recommended validation path here?

From the repository root: make pytest, make lint, make typecheck, and make test.

About Contributions

About Contributions: Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

MIT