Part 1: Foundations¶
6. Understanding the Stack¶
“Structure isn’t built in a vacuum. It reflects your stack’s behavior.”
Why Stack Awareness Matters¶
Your folder structure should mirror how your app works—not fight it.
You can’t structure a React + FastAPI app the same way you would structure a monolithic Rails app or a serverless function chain. The communication style, state boundaries, and build process between frontend and backend shape how your code should be organized.
This chapter gives you a bird’s-eye view of the React + FastAPI full-stack architecture—so you know what you’re structuring and why certain patterns emerge.
Let’s break it down.
React + Vite: The Frontend¶
React is a component-driven UI library. Vite is its next-gen build tool, optimized for speed and modularity.
Key Characteristics:¶
- File-based routing (via React Router, not enforced by framework)
- Component reusability is encouraged (hooks, context, UI libraries)
- Client-side rendering by default
- Modular JavaScript/TypeScript imports
- Single-page application model, often talking to an API backend
- Optional integrations: state management (Zustand, Redux, Jotai), form libs, TailwindCSS, etc.
Frontend Folder Design Considerations:¶
-
You’ll likely need folders for:
-
components/
: shared visual components features/
: domain-based modules (e.g., chatbot, invoice)hooks/
: reusable logicapi/
: backend interaction (e.g., axios or fetch wrappers)assets/
: static images, videos, iconsroutes/
: layout-level control (React Router v6)context/
orstore/
: global or scoped state
Common Patterns:¶
- Feature-first foldering is often better early on
- Shared logic moves into
shared/
orlib/
as complexity grows - Components are often colocated with CSS or styled using utility-first approaches (e.g., Tailwind)
FastAPI: The Backend¶
FastAPI is a modern Python web framework built on Pydantic and Starlette. It’s API-first, type-hinted, and async-ready.
Key Characteristics:¶
- Route-first design: APIs are defined via decorators (
@router.get
,@router.post
) - Request validation and serialization via Pydantic schemas
- ASGI-native: supports WebSockets, streaming, background tasks
- Auto-docs via OpenAPI, great for teams and testing
- Flexible architecture: microservice-ready, but can be modular or monolithic
Backend Folder Design Considerations:¶
-
Key layers include:
-
api/
: all route logic schemas/
: request/response Pydantic modelsservices/
: business logiccore/
: config, constants, middlewareinfra/
: database, vector DBs, storage clientsutils/
orshared/
: generic reusable helperstests/
: unit + integration test structure
Common Patterns:¶
- Layer-first is preferred for complex or team-sized projects
- Dependency injection (via
Depends
) supports testability - Router composition (e.g.,
include_router()
) allows per-module routing logic - Can be modularized per feature or layered—or both (hybrid)
How React and FastAPI Communicate¶
The two parts of your stack are decoupled—but tightly integrated.
Communication Layer | Tech | Structure Tip |
---|---|---|
REST API | JSON over HTTP | Use an api/ folder on both frontend and backend |
WebSockets | Real-time, duplex | Isolate WS logic in a shared sockets/ or events/ layer |
Streaming | yield from backend → chunks in frontend |
Group stream handlers and frontend consumers as a unit |
File Uploads | multipart/form-data |
Create a unified upload/ or documents/ module |
Authentication | JWT, OAuth, sessions | Mirror auth/ logic in both frontend and backend features |
Embeddings/Vector Search | Supabase, Pinecone, Weaviate | Treat as an infrastructure concern in infra/ or services/ |
Shared Challenges in a Full-Stack AI App¶
With React + FastAPI, especially in AI-centric use cases (e.g., OCR, GPT, chatbots), you face shared architectural challenges that should influence folder design:
1. State Synchronization¶
- React stores client-side UI state, auth state, and sometimes cached data
- Backend stores ground truth (e.g., user sessions, file uploads, GPT responses)
- Solution: use
context/
orstore/
in React + strict separation ofservices/
andapi/
in FastAPI
2. API Versioning¶
- As your API grows, changes must be non-breaking
- Solution: versioned routers (e.g.,
api/v1/chat.py
,api/v2/chat.py
) and API clients on frontend
3. Authentication & Authorization¶
- Frontend handles token storage (often via HTTP-only cookies or
localStorage
) - Backend must validate tokens on each request
- Solution:
auth/
folders in both front and back, shared schema if monorepo
4. Model Wrapping and Latency¶
- GPT calls, vector DB lookups, or OCR take time
- Use background jobs (
BackgroundTasks
, Celery) and streaming where appropriate
5. Error Handling and Logging¶
- Frontend: user-friendly messages, fallback states
- Backend: structured logs,
try/except
middleware, Sentry integration
Summary: Structure Reflects Stack Realities¶
Layer | React (Vite) | FastAPI |
---|---|---|
Presentation | components/ , routes/ |
N/A (or static templates) |
State | context/ , store/ , hooks/ |
Depends() , middleware, DB |
API Integration | api/ , services/ |
api/ , schemas/ , services/ |
Business Logic | features/ , services/ |
services/ , core/ , infra/ |
Shared Logic | shared/ , lib/ |
shared/ , utils/ |
Tests | __tests__/ , colocated with features |
tests/ , per module or per layer |
A well-structured project doesn’t just separate concerns—it reflects the shape of your stack.