Python 1,315 FILES 13 FINDINGS

HOW REFLEX
ACTUALLY WORKS

Build full-stack web apps in pure Python. Conventions, patterns, and architecture extracted from the reflex-dev/reflex repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Validation: @dataclass Testing: pytest Database: SQLAlchemy Framework: FastAPI

WHAT_MATTERS

→
FastAPI project — use Pydantic models for request/response schemas, not raw dicts
→
reflex/__init__.py is a hub file (imported by 53 files) — changes here ripple everywhere
→
This is both a monorepo and a publishable library — check workspace dependencies and avoid breaking the public API

KEY_FINDINGS

FastAPI project. Use Pydantic models for request/response schemas, not raw dicts.

HIGH

Uses SQLAlchemy/SQLModel for ORM. Database sessions must be properly closed (use dependency injection).

HIGH

Uses pytest. Test files should be named test_*.py or *_test.py.

HIGH

16 test files

This is a monorepo. Changes may affect multiple packages.

HIGH

Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files.

HIGH

This is a publishable library. Focus changes on the public API surface.

HIGH

Uses __init__.py as barrel exports. Import from the package, not from internal modules.

HIGH

14 non-empty __init__.py files

Use @dataclass for data structures.

HIGH

14 files use dataclasses

Database access uses SQLAlchemy. Look for schemas in models/.

HIGH

2 files

UI components live in: docs/app/assets/components.

HIGH

1 component directory

Hub files: reflex/__init__.py (53 files); reflex/vars/base.py (33 files); reflex/utils/__init__.py (29 files); reflex/components/component.py (29 files); reflex/event.py (22 files). Changes here have the widest blast radius.

HIGH

Circular imports: experimental/__init__.py; reflex_components_react_player/__init__.py; el/__init__.py. Avoid adding to these cycles.

HIGH

smart_toy USING_AI_TOOLS

→use Pydantic models for API schemas, not raw dicts
→check file importance before editing hub files (reflex/__init__.py has 53 dependents)
→follow pytest conventions for test naming

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **validation:** @dataclass
- **testing:** pytest
- **database:** SQLAlchemy
- **framework:** FastAPI

## Commands

- **Test:** `pytest`
- **Lint:** `ruff check .`

## Critical Constraints

- **Testing:** Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files.
- **Core modules:** Hub files (most depended on): reflex/__init__.py (imported by 53 files); reflex/vars/base.py (imported by 33 files); reflex/utils/__init__.py (imported by 29 files); reflex/components/component.py (imported by 29 files); reflex/event.py (imported by 22 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular imports: experimental/__init__.py; reflex_components_react_player/__init__.py; el/__init__.py. Avoid adding to these cycles.

## Stack

FastAPI, Python

## Project Structure

- `tests/` — Tests
- `docs/` — Documentation
- `scripts/` — Scripts

## Core Modules (by structural importance)

- `reflex/__init__.py`
- `reflex/utils/__init__.py`
- `reflex/vars/base.py`
- `reflex/components/component.py`
- `reflex/event.py`

## Conventions & Patterns

- **Import conventions:** Uses __init__.py as barrel exports. Import from the package, not from internal modules.
- **Dominant patterns:**
- Uses pytest. Test files should be named test_*.py or *_test.py.
- Database access uses SQLAlchemy. Look for schemas in models/.
- Use @dataclass for data structures.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

FASTAPI DJANGO

HOW REFLEXACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW REFLEX
ACTUALLY WORKS