How buuntu/fastapi-react works
Project Type and Purpose
• This is a full-stack, containerized web application template combining:
• A FastAPI back-end (Python) providing a JWT-secured REST API and background tasks via Celery/Redis.
• A React front-end (TypeScript, MaterialUI + react-admin) consuming that API.
• PostgreSQL for persistence, Alembic for migrations.
• Docker Compose orchestrating containers (frontend, backend, DB, Redis, Celery, Flower, Nginx).
Main Components
a. Reverse Proxy (Nginx)
• nginx.conf routes incoming HTTP(S) to either the React dev server/static build or the FastAPI Uvicorn server.
b. Frontend Service
• React application served by a Node.js container (development server via npm start or static files in production).
• Contains routes (login, home, protected), utilities (auth, API calls), and an admin dashboard (react-admin).
c. Backend Service
• FastAPI application running under Uvicorn/Gunicorn.
• API layer: routers (auth.py, users.py) organized under /app/api/api_v1/routers.
• Core logic: authentication, config, Celery app, security, dependencies.
• Persistence: SQLAlchemy models/schemas, session management, Alembic migrations, initial_data loader.
• Background tasks: app/tasks.py, Celery configured to use Redis broker.
d. Database
• PostgreSQL container, accessed by FastAPI (CRUD operations) and by tests via test_db fixture.
e. Message Broker & Workers
• Redis as Celery broker.
• Celery worker container consuming tasks.
• Flower container for monitoring tasks at port 5555.
f. CI / CD and Scripts
• GitHub Actions for builds, Dependabot config.
• Local scripts (build.sh, test.sh, etc.) for building images, running tests, migrations.
Component Interactions and Data Flows
• Client → Nginx: All HTTP traffic enters through Nginx.
• Nginx → Frontend: Routes GET /, static files or dev server proxy.
• Frontend ↔ Backend: React invokes REST endpoints under /api/v1/... using JWT in headers.
• Backend → PostgreSQL: CRUD via SQLAlchemy sessions.
• Backend → Redis: Celery tasks dispatched to broker.
• Redis → Celery Workers: Workers pick up tasks, optionally perform DB operations.
• Celery Workers → Flower: Flower polls broker/worker metrics.
Architectural Patterns and Design Principles
• Layered Architecture: Presentation (React), API/Business (FastAPI), Data (PostgreSQL), Background Processing (Celery).
• Containerization & Microservices: Each logical component runs in its own Docker container, networked via Docker Compose.
• Separation of Concerns:
• Frontend (frontend/) vs. Admin (frontend/src/admin/) vs. Utils.
• Backend modules: routers, core, db, tasks.
• Infrastructure as Code: Dockerfiles, compose file, Nginx config, scripts.
• Testing Strategy: Pytest fixtures isolate test DB and clients; React unit tests under __tests__.
Technologies and Frameworks
• Frontend: React, react-router, MaterialUI, react-admin, TypeScript, ESLint/Prettier.
• Backend: FastAPI, Uvicorn/Gunicorn, Pydantic, SQLAlchemy, Alembic, PyJWT, Celery, Redis.
• Database: PostgreSQL.
• Orchestration: Docker Compose, Nginx.
• CI/CD: GitHub Actions, Dependabot.
Essential Elements Checklist
• Logical grouping of frontend, backend, data, and infrastructure.
• Port numbers and network names.