Flux

Flux is a modern full-stack application built with FastAPI and React, utilizing Refine for the frontend and Shadcn UI for components. It leverages devenv for a reproducible development environment.

Tech Stack

Backend

• Framework: FastAPI
• Database ORM: SQLAlchemy
• Migrations: Alembic
• Authentication: OAuth2 with JWT (python-jose, passlib)
• Linting & Formatting: Ruff
• Type Checking: ty
• Testing: Pytest

Frontend

• Framework: React 19
• Build Tool: Vite
• Data Framework: Refine
• UI Components: Shadcn UI, Radix UI
• Styling: Tailwind CSS
• Form Handling: React Hook Form
• Validation: Zod

Prerequisites

• Nix
• devenv
• Bun 1.3.x (automatically provided inside devenv)

Getting Started

This project uses devenv to manage dependencies and services.

1. Clone the repository:

   git clone <repository-url>
   cd fluxapp
   

2. Start the development environment:

   devenv up
   

   This command will start all necessary services, including the backend API and frontend development server.

Runtime Configuration

Configuration is loaded from environment variables (backend/.env, frontend/.env) with examples in:

• backend/.env.example
• frontend/.env.example

Backend variables

Variable	Local development	Production	Notes
ENVIRONMENT	Optional (development default)	Required (production)	Controls strict config guards
DATABASE_URL	Required (can use local DB URL)	Required (must not use local default)	Backend startup fails outside development if left at local default
SECRET_KEY	Optional	Required	Backend startup fails outside development if missing or placeholder
FRONTEND_URL	Required	Required	Used in auth email links
SENTRY_DSN	Optional	Optional	If set, must not be a placeholder
SMTP_*, EMAILS_*, DB_*	Optional	Optional/recommended	Email + pool tuning

Frontend variables

Variable	Local development	Production	Notes
VITE_API_URL	Required	Required	Frontend boot fails if missing/placeholder/invalid
VITE_APP_ENVIRONMENT	Optional (development)	Required (production)	Used for strict runtime checks
VITE_SENTRY_DSN	Optional	Required	Frontend boot fails outside development if missing/placeholder

Deployment

This repo is deployed as two services:

• Backend API on Fly.io, built from the api devenv container
• Frontend SPA on Netlify
• Database on Neon and media storage on S3

Fly API flow

1. Log in to Fly once with flyctl auth login.
2. Build the backend image from devenv:

   devenv container build api
   

3. Push that image to Fly's registry:

   devenv container copy api \
     --registry docker://registry.fly.io/ \
     --copy-args="--dest-creds x:$(flyctl auth token)"
   

4. Create the Fly app without deploying yet, and make sure the service port is 8000:

   fly launch --image registry.fly.io/flux-api:<tag> \
     --name flux-api \
     --no-db \
     --no-object-storage \
     --no-deploy \
     --internal-port 8000
   

5. Set the runtime secrets on Fly:

   fly secrets set \
     DATABASE_URL='postgresql://...' \
     SECRET_KEY='...' \
     FRONTEND_URL='https://your-frontend-domain' \
     MEDIA_S3_ENDPOINT_URL='...' \
     MEDIA_S3_BUCKET='...' \
     MEDIA_S3_ACCESS_KEY_ID='...' \
     MEDIA_S3_SECRET_ACCESS_KEY='...'
   

   Add SENTRY_DSN, SMTP_*, or DB_* as needed. Set MEDIA_S3_REGION and MEDIA_S3_FORCE_PATH_STYLE only if your S3 provider needs them.
6. Deploy the same image:

   fly deploy --image registry.fly.io/flux-api:<tag>
   

The container starts by running alembic upgrade head and then uvicorn.

Netlify Frontend flow

1. Create a new Netlify site from the same repo.
2. Set the base directory to frontend.
3. Netlify reads frontend/netlify.toml, runs bun run build, and publishes dist. Bun is detected from frontend/bun.lock.
4. Set the Netlify environment variables for production:

   VITE_API_URL=https://<your-fly-api>.fly.dev
   VITE_APP_ENVIRONMENT=production
   VITE_SENTRY_DSN=...
   

5. Deploy the site, then copy the Netlify URL into Fly as FRONTEND_URL.

If you use a custom domain on Netlify, point FRONTEND_URL at that domain instead.

Project Structure

fluxapp/
├── backend/          # FastAPI application
│   ├── app/          # Application source code
│   ├── alembic/      # Database migrations
│   └── tests/        # Backend tests
├── frontend/         # React application
│   ├── src/          # Frontend source code
│   └── public/       # Static assets
├── devenv.yaml       # Development environment configuration
└── README.md         # Project documentation

Documentation

• Backend Development Guide
  • Adding Models
  • Creating Endpoints
  • Migrations
• Frontend Development Guide
  • Generating API Client
  • Adding Views & Columns
  • Form Validation

Development

Pull Request Quality Gates

Every pull request runs CI quality gates for backend and frontend checks. A PR is merge-ready only when all jobs pass.

Required checks:

• generated-client-sync: runs ./scripts/generate-client.sh and fails if backend/openapi.json or frontend/src/lib/api-client/ changes.
• backend-quality: runs uv run ruff check ., uv run ty check ., and uv run pytest in backend/.
• frontend-quality: runs bun run lint, bunx tsc --noEmit, bun run test, and bun run build in frontend/.

Expected pass criteria before merge:

• Every command exits with status 0.
• No generated API/client drift remains after ./scripts/generate-client.sh.

Backend

Navigate to the backend directory:

cd backend

• Run Tests:

  pytest
  

• Linting:

  ruff check .
  

• Type Checking:

  ty check .
  

Frontend

Navigate to the frontend directory:

cd frontend

• Start Dev Server:

  bun run dev
  # or
  refine dev
  

• Build for Production:

  bun run build
  

• Linting:

  bun run lint
  

Canonical Feature + API Sync Workflow

1. Update backend models/schemas/endpoints in backend/.
2. Regenerate the frontend API client from the repo root:

   ./scripts/generate-client.sh
   

   (or use the helper command api-generate inside devenv)
3. Wire generated client methods in frontend/src/providers/generated-provider.ts and register routes/resources in frontend/src/App.tsx.
4. Use generated validation schemas from frontend/src/lib/api-client/zod.gen.ts as the form validation source of truth.