ShiftIt — Documentation Index

Generated: 2026-05-10 by bmad-document-project (initial scan, deep level). Update via /document-project (or its successor) — the workflow is brownfield-aware and supports re-scan, deep-dive, or selective regeneration.

This index is the primary AI retrieval entry point for the ShiftIt project. New contributors and AI agents should read project-overview.md first, then drill into per-part architecture as needed.

Project at a glance

  • Type: monorepo (Cargo workspace) with 2 parts + 1 standalone tool crate

  • Primary languages: Rust (backend stable, frontend nightly)

  • Architecture: modular monolith REST API (Axum) + WASM SPA (Leptos), connected over /api/v1

  • Multi-tenancy: PostgreSQL Row-Level Security (RLS) with per-request app.tenant_id

  • Auth: Zitadel OIDC issuer; backend is a pure resource server

Parts

Backend (backend/) — shiftit-backend

  • Type: Rust modular monolith REST API

  • Stack: Axum 0.8, sqlx 0.8, PostgreSQL 16 (RLS), utoipa, jsonwebtoken, web-push, aws-sdk-s3

  • Entry point: backend/src/main.rs

  • Auth: Validates Zitadel JWTs against JWKS; injects TenantContext into every request

  • Key concept: TenantContext::rls_transaction(&pool) → tenant-scoped DB transaction (set the GUC, let Postgres enforce isolation)

Frontend (frontend/) — shiftit-frontend

  • Type: Rust → WASM SPA + PWA

  • Stack: Leptos 0.8 (CSR + nightly), Trunk, Tailwind v4, rust-ui (MIT)

  • Entry point: frontend/src/main.rs → mounts <App/> from frontend/src/app.rs

  • Three surfaces: /admin/ (10 pages), /app/ (5 pages, employee), /f/{slug} (customer form)

  • Build target: wasm32-unknown-unknown; pinned nightly toolchain in frontend/rust-toolchain.toml

Generated documentation

Doc What it covers

Project Overview

One-pager: what ShiftIt is, where everything lives

Source Tree Analysis

Annotated directory tree per part

Integration Architecture

How frontend talks to backend (/api/v1, JWT, DTOs)

Architecture — Backend

Backend internals: layering, auth pipeline, RLS, OpenAPI

Architecture — Frontend

Frontend internals: surface segmentation, data flow patterns

API Contracts — Backend

Endpoint catalog organised by tag (mirrors /api/docs/)

Data Models — Backend

Schema per migration, RLS policies, FK relationships

Component Inventory — Frontend

rust-ui primitives + per-surface page catalog

Development Guide

Daily dev loop, build/test commands, conventions, troubleshooting

Deployment Guide

Compose stack, env vars, CI/CD, build modes

docs/project-parts.json (machine-readable structure metadata) is kept in the repo alongside the docs but is not part of the published component.

Existing documentation (preserved)

Doc Description

CLAUDE.md (repo root — not part of the portal)

Project handover doc. Run-the-dev-stack and architectural facts the next session must know. Read this first if you are coding.

notes/follow-ups.adoc (repo process artifact — not published)

Outstanding work, prioritised. P0/P1/P2 — every new task should be picked from here

Licensing

License signing & shipping flow for self-hosted builds

Deployment — binary

Bare binary + nginx without Compose

Deployment — Docker Compose

Annotated Compose walkthrough

Deployment — Nginx

TLS termination + reverse proxy config

Deployment — Zitadel setup

OAuth app config, claim mapping (⚠️ verify v1/v2 action API per current Zitadel)

docs/superpowers/specs/2026-05-08-shiftit-design.md (repo — not published)

Frozen — what the system should be. Reference, not current state

docs/superpowers/plans/ (repo — not published)

Frozen per-plan walkthroughs from the superpowers workflow

Ideas & exploration

Speculative bets and the autonomous-run decision trail live in the repo’s notes/ folder (process artifacts, excluded from the portal):

  • notes/wild-ideas.adoc — speculative, uncommitted bets. #1: managed Device-Owner tablets + custom forms + PoS + fleet control as a service line (osd-proven kiosk pattern; logistics/events/field-service verticals).

  • notes/autonomous-decision-log.adoc — decisions made during no-human-in-the-loop sessions, each with rationale + revert path.

Getting started

  1. Read ../CLAUDE.md — this is the canonical "how to run the dev stack" doc and tells you about RLS, the dev-auth bypass, and the migration discipline.

  2. Run the dev stack — three terminals: Postgres (Docker), python3 scripts/mock-jwks.py 9999, ./scripts/run-backend.sh admin, cd frontend && trunk serve.

  3. Open http://localhost:3010/api/docs/ to browse the live API surface.

  4. Open http://localhost:8080/ for the frontend, then paste this in the console once to enter auth-gated UI:

    localStorage.setItem('shiftit_token', JSON.stringify('dev')); location.reload();

  5. Pick a follow-up from docs/follow-ups.md — the file is the source of truth for what’s next.

For AI agents (brownfield workflow notes)

  • Picking work: every new task should map to an entry in docs/follow-ups.md. New work that doesn’t fit an existing entry should add a new one rather than scattering TODOs in code.

  • Reading the codebase: architecture-backend.md and architecture-frontend.md give you the conceptual layout; source-tree-analysis.md gives you the file-level map; the OpenAPI doc at /api/docs/ is the live API surface.

  • Tenant isolation invariant: every backend DB operation must run via ctx.rls_transaction(&pool). The single bypass (customer_forms_lookup_by_slug) is documented in architecture-backend.md and data-models-backend.md.

  • Migration discipline: if you add migrations, follow Plan 02 conventions (see development-guide.md); if you edit existing migrations, dev DBs must be reset (procedure in CLAUDE.md).

  • OpenAPI registration: new routes need three updates — #[utoipa::path], main.rs::create_router, and openapi.rs::ApiDoc::paths. The third is easy to forget.