How iloveitaly/python-starter-template works
Main System Components
a) Frontend Layer:
• React + React Router SPA application
• UI Components (ShadCN + Tailwind)
• TypeScript integration
• Frontend tooling (Vite, Vitest, ESLint)
b) Backend Layer:
• FastAPI application
• SQLModel + SQLAlchemy ORM
• Alembic migrations
• Celery job processing
c) Data Layer:
• PostgreSQL database
• Redis cache
d) External Services Layer:
• Clerk (Authentication)
• Sentry (Error tracking)
• PostHog (Analytics)
• Mailpit (Email testing)
Component Relationships
a) Client-Server Communication:
• Frontend → Backend (OpenAPI/REST)
• Type safety through generated TypeScript types
b) Data Flow:
• Backend → Database (SQLAlchemy)
• Backend → Redis (Caching/Jobs)
• Backend → External Services
Development Infrastructure
A separate section showing:
• Docker Compose environment
• Development tooling (Justfile, Direnv, Mise)
• Testing infrastructure (Playwright, Pytest)
Specific Implementation Details
a) Authentication Flow:
• Clerk integration with both frontend and backend
• User session management
b) API Layer:
• FastAPI routes structure
• Middleware pipeline
• Dependencies injection
c) Database Architecture:
• Model relationships
• Migration system
• TypeID implementation
Key Architectural Patterns to Highlight
• Clear separation between frontend and backend
• Type safety across the stack
• Container-based deployment
• Environment-based configuration
• Testing pyramid (unit, functional, integration)