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

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.