Architecture

Architecture

PrintStash is a FastAPI backend, a Vite/React frontend, and a storage layer that starts simple on SQLite/local disk.

Browser / scripts / OrcaSlicer
          |
          v
Vite/React UI + FastAPI API
          |
          +-- ingestion, metadata extraction, thumbnails
          +-- taxonomy, search, auth, audit, backup
          +-- printer providers: Moonraker stable, Bambu LAN beta
          |
          v
SQLite + local files by default
Postgres + S3/R2 optional

Repository Layout

backend/
  app/
    api/v1/        FastAPI routers
    core/          config, security, HTTP, logging
    db/            SQLModel models and session factory
    schemas/       Pydantic request/response schemas
    services/      business logic, no HTTP dependencies
  alembic/         DB migrations
  tests/           pytest suite

frontend/
  src/
    components/    feature components and UI primitives
    lib/api/       domain API clients
    pages/         React Router pages
    router.tsx     route definitions
    types/         TypeScript domain types

Request Flow

HTTP request
  -> middleware
  -> api/v1/<router>.py
  -> services/<service>.py
  -> db/session.py
  -> db/models.py

Rules:

• Routers never import other routers.
• Services never import from api/ or fastapi.
• Services import from db/session, db/models, schemas/, and core/config.
• Runtime config reads use get_config().
• Frontend API calls use src/lib/api/<domain>.ts, not raw fetch.

Architecture Decisions

• ADR-0001: SessionFactory via ContextVar
• ADR-0002: Frozen settings plus runtime overlay

Provider Layer

Printer integrations go through provider abstractions:

• Moonraker/Klipper: stable
• Bambu LAN: beta, status/control only today

Capability details live in provider support.