TrackStack v2

TrackStack v2 is a multi-tenant logistics platform for managing projects, materials, assets, vendor collaboration, and transfer workflows.

Tech Stack

Layer	Choice
Backend framework	FastAPI
ORM	SQLAlchemy 2.x (async, via asyncpg)
Database	PostgreSQL 16
Auth	Custom JWT access tokens + opaque refresh tokens
Password hashing	Argon2id (primary), bcrypt (fallback)
Frontend framework	React 19
Build tool	Vite
CSS	Tailwind CSS
Language	TypeScript (strict mode)
Server state	TanStack Query v5
Forms	React Hook Form + Zod
Routing	React Router v7
Infrastructure	Docker Compose for local dev

Getting Started

Prerequisites

• Docker Desktop with Docker Compose support
• Node.js 22+
• Python 3.12+

Quick Start

# 1. Copy the environment template
cp .env.example .env

# 2. Install the root toolchain
npm install

# 3. Install frontend dependencies
npm run install:frontend

# 4. Start Docker services plus the local Vite dev server
npm run dev:full

# 5. Run shared migrations inside the backend container
docker compose exec backend python scripts/run_migrations.py

# 6. Bootstrap the first superadmin
docker compose exec backend python scripts/create_superadmin.py --email admin@trackstack.local

This starts PostgreSQL, MinIO, and the FastAPI backend in Docker, while the React frontend runs locally for fast hot module reload.

For a production-style all-container run, use npm run docker:up to include the built frontend container as well.

Bootstrap The First Superadmin

After the backend container is running and shared migrations have been applied, create the first platform superadmin from the repo root:

docker compose exec backend python scripts/create_superadmin.py --email admin@trackstack.local

You can also pass --password <value> directly, but omitting it is safer because the script prompts securely.

Run Shared Migrations

Apply shared-schema migrations against the running database:

docker compose exec backend python scripts/run_migrations.py

If there are no new migrations, the script reports that there are no pending shared migrations.

The bootstrap command is idempotent:

• If a superadmin already exists, it prints a message and exits without creating a duplicate.
• If the email already belongs to another user, it prints guidance and exits non-zero.
• New superadmin users are created as active, email-verified platform administrators.

Provision And Verify Tenant Routing

Once the backend is running and a superadmin can authenticate, you can exercise the M2 tenant provisioning and routing flow end to end:

# Create a tenant from the platform layer.
curl -X POST http://127.0.0.1:8000/api/admin/tenants \
  -H "Authorization: Bearer <superadmin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Telecom",
    "slug": "acme-telecom",
    "owner_user_id": "<owner_user_uuid>"
  }'

# List the tenants the current user can access.
curl http://127.0.0.1:8000/api/tenants \
  -H "Authorization: Bearer <access_token>"

# Verify tenant-scoped routing against the active tenant schema.
curl http://127.0.0.1:8000/api/tenants/<tenant_uuid>/ping \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-Id: <tenant_uuid>"

When npm run dev:frontend or npm run dev:full is running, the temporary frontend verification surface at http://127.0.0.1:3000/login lists tenant memberships, lets you switch the active tenant, and includes a Test Tenant Request button to confirm X-Tenant-Id injection through the frontend API client.

Manual Start

If you want separate terminals without using npm run dev:full, keep the backend in Docker and start only the frontend locally:

# Backend services
docker compose up -d db minio backend
docker compose exec backend python scripts/run_migrations.py

# Frontend (separate terminal)
npm run dev:frontend

Full Docker Start

docker compose up --build

Available Scripts

Command	Purpose
npm run dev:full	Launch Docker services (db, minio, backend) and the local Vite frontend together
npm run dev:services	Launch only Docker services
npm run dev:frontend	Launch only the Vite dev server
npm run docker:up	Build and start all Docker services, including the frontend container
npm run docker:down	Stop all Docker services
npm run install:frontend	Install frontend npm dependencies

Project Structure

.
├── backend/               # FastAPI application and backend tooling
│   ├── app/
│   │   ├── api/
│   │   │   ├── dependencies/  # FastAPI Depends helpers (auth, tenant context)
│   │   │   └── routes/        # HTTP route handlers (thin)
│   │   ├── core/          # Config, DB, security, errors, logging
│   │   ├── integrations/  # External provider interfaces
│   │   ├── middleware/    # Request ID, auth context, tenant context
│   │   ├── models/
│   │   │   ├── shared/    # SQLAlchemy models for public schema
│   │   │   └── tenant/    # SQLAlchemy models for tenant schemas
│   │   ├── repositories/
│   │   │   ├── shared/    # Data access for public schema
│   │   │   └── tenant/    # Data access for tenant schemas
│   │   ├── schemas/       # Pydantic request/response models
│   │   ├── services/      # Business logic (grouped by domain)
│   │   └── ws/            # WebSocket handlers
│   ├── migrations/
│   │   ├── shared/        # Shared schema SQL migrations
│   │   └── tenant/        # Tenant schema template migrations
│   ├── scripts/           # Admin and provisioning helpers
│   └── tests/
├── frontend/              # React application
│   └── src/
│       ├── app/           # App bootstrap and router
│       ├── components/    # Shared UI primitives
│       ├── context/       # Simple React contexts
│       ├── features/      # Domain feature modules
│       ├── layouts/       # Shell layouts
│       ├── lib/           # API client, auth-api, admin-api, branding-api
│       ├── pages/         # Route pages
│       ├── providers/     # Query, auth, tenant, and app providers
│       ├── routes/        # Route definitions and guards
│       └── types/         # Shared frontend types
├── docs/                  # Sprint plans and evolving project docs
├── docker/                # Dockerfiles and container support assets
├── V1 Docs/               # Foundational architecture reference set
├── docker-compose.yml     # Local development stack
├── AGENTS.md              # Project-wide coding and architecture rules
├── package.json           # Root workspace scripts
└── .env.example           # Environment template

Architecture Summary

TrackStack v2 uses schema-per-tenant isolation:

• The shared public schema stores platform-wide records such as users, tenants, memberships, and auth sessions.
• Each tenant gets its own tenant_<uuid_prefix> schema for business data such as projects, materials, assets, vendors, transfers, and notifications.
• Tenant-scoped API requests require X-Tenant-Id, and backend membership checks must happen before setting the database search_path.

The frontend is organized into four surfaces:

• Public marketing/auth routes
• Client dashboard shell
• Vendor portal shell
• Superadmin shell

Documentation

Document	Purpose
V1 Docs/00-architecture-overview.md	Architecture overview and core decisions
V1 Docs/01-glossary.md	Canonical vocabulary and naming rules
V1 Docs/02-multi-tenant-architecture.md	Schema-per-tenant design
V1 Docs/03-authentication.md	JWT auth and refresh token design
V1 Docs/04-authorization-rbac.md	RBAC layers and authorization rules
V1 Docs/05-database-schema.md	Shared and tenant schema design
V1 Docs/06-backend-architecture.md	Backend layering and conventions
V1 Docs/07-api-specification.md	API contracts and endpoint conventions
V1 Docs/08-frontend-architecture.md	Frontend shell, state, and routing design
V1 Docs/09-vendor-portal.md	Vendor access model and portal behavior
V1 Docs/10-infrastructure.md	Local infrastructure and deployment guidance
V1 Docs/11-migration-guide.md	Legacy migration and phased rollout notes
V1 Docs/milestones/	Milestone-by-milestone implementation plan