Skip to content
This repository was archived by the owner on Apr 28, 2026. It is now read-only.

Commit 34824d0

Browse files
Alek99claude
Alek99
and
claude
committed
Add CLAUDE.MD context file for AI development
This file provides comprehensive project context for Claude AI sessions, including: - Project overview and tech stack - Directory structure and key files - Development workflow and testing procedures - Common tasks and code patterns - Architecture notes and deployment info This will help AI assistants better understand the project structure and provide more accurate assistance. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 06958dd commit 34824d0

1 file changed

Lines changed: 308 additions & 0 deletions

File tree

‎CLAUDE.MD‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Reflex Website - Claude AI Context
2+
3+
## Project Overview
4+
5+
**Project:** reflex-web - The official website and documentation for Reflex
6+
**Repository:** https://github.com/reflex-dev/reflex-web
7+
**Purpose:** Marketing, documentation, and showcase website for Reflex, a Python framework for building full-stack web applications
8+
9+
The website is built using Reflex itself, demonstrating the framework's capabilities while providing comprehensive documentation, tutorials, blog posts, and templates.
10+
11+
## Tech Stack
12+
13+
### Core Technologies
14+
- **Reflex** (Python framework) - Full-stack web framework with Python backend and React frontend
15+
- **Python 3.11+** - Primary language
16+
- **FastAPI** - Backend API framework (integrated with Reflex)
17+
- **React** - Frontend (abstracted through Reflex components)
18+
- **Tailwind CSS v4** - Styling with custom plugins
19+
- **Radix UI** - Accessible UI component library
20+
21+
### Database & ORM
22+
- **PostgreSQL** - Primary database (production)
23+
- **SQLite** - Local development (`reflex.db`)
24+
- **SQLAlchemy** - ORM layer
25+
- **Alembic** - Database migrations
26+
27+
### Development Tools
28+
- **uv** (>=0.7.0) - Python package manager
29+
- **Ruff** - Python linter and formatter (targets Python 3.11)
30+
- **Pytest** - Unit testing
31+
- **Playwright** - E2E testing
32+
- **Pre-commit** - Git hooks for code quality
33+
34+
### External Services
35+
- **OpenAI API** - AI features
36+
- **Typesense** - Search functionality
37+
- **Loops.so** - Email marketing
38+
- **Replicate** - ML model serving
39+
- **Google Translate API** - Internationalization
40+
- **Zapier Webhooks** - Form integrations
41+
42+
## Project Structure
43+
44+
```
45+
reflex-web/
46+
├── pcweb/ # Main Reflex application
47+
│ ├── pages/ # Page components (landing, docs, blog, pricing, etc.)
48+
│ ├── components/ # Reusable UI components (22 subdirectories)
49+
│ ├── templates/ # Layout templates (mainpage, webpage, docpage, etc.)
50+
│ ├── styles/ # Global styles (colors, fonts, shadows)
51+
│ ├── views/ # Page view sections
52+
│ ├── meta/ # SEO metadata
53+
│ ├── telemetry/ # Analytics
54+
│ ├── constants.py # URLs and configuration constants
55+
│ ├── models.py # Database models
56+
│ ├── route.py # Route definitions
57+
│ ├── flexdown.py # Custom markdown processor
58+
│ └── pcweb.py # Main app configuration
59+
│
60+
├── docs/ # Documentation markdown files
61+
│ ├── getting_started/ # Getting started guides
62+
│ ├── ui/ # UI component docs
63+
│ ├── database/ # Database docs
64+
│ ├── library/ # Component library docs
65+
│ ├── enterprise/ # Enterprise features (AG Grid, Mantine, React Flow)
66+
│ └── api-reference/ # API documentation
67+
│
68+
├── blog/ # Blog posts (29+ markdown files)
69+
├── reflex_build_templates/ # Pre-built templates (18 dashboards & apps)
70+
├── case-studies/ # Customer case studies
71+
├── integrations-docs/ # Integration documentation
72+
├── tests/ # Test suite (pytest, Playwright)
73+
├── assets/ # Static assets (66 subdirectories)
74+
├── alembic/ # Database migrations
75+
│
76+
├── rxconfig.py # Reflex app configuration
77+
├── tailwind_config.py # Tailwind CSS theme
78+
├── pyproject.toml # Python dependencies
79+
├── uv.lock # Locked dependency versions
80+
└── README.md # Project README
81+
```
82+
83+
## Key Files
84+
85+
### Configuration
86+
- `rxconfig.py:1` - Main Reflex config (port 3000, plugins, environment)
87+
- `tailwind_config.py:1` - Tailwind theme customization
88+
- `tailwind_radix_map.py:1` - Tailwind-Radix color mapping
89+
- `pyproject.toml:1` - Python project metadata and dependencies
90+
91+
### Core Application
92+
- `pcweb/pcweb.py:1` - Main app setup with routes, redirects, styling (166 lines)
93+
- `pcweb/route.py:1` - Route definition dataclass
94+
- `pcweb/constants.py:1` - External URLs and API endpoints
95+
- `pcweb/flexdown.py:1` - Custom markdown processor for docs
96+
97+
### Styling System
98+
- `pcweb/styles/styles.py:1` - Base style configuration
99+
- `pcweb/styles/colors.py:1` - Color constants (Radix palette)
100+
- `pcweb/styles/fonts.py:1` - Font definitions (Instrument Sans, JetBrains Mono)
101+
- `pcweb/styles/shadows.py:1` - Shadow definitions
102+
103+
### Database
104+
- `pcweb/models.py:1` - Database models (Customer model)
105+
- `alembic/env.py:1` - Migration environment configuration
106+
107+
## Development Workflow
108+
109+
### Setup
110+
```bash
111+
# Install dependencies
112+
uv sync
113+
114+
# Run development server
115+
reflex run
116+
117+
# Open browser at http://localhost:3000
118+
```
119+
120+
### Testing
121+
```bash
122+
# Run unit tests
123+
pytest
124+
125+
# Run integration tests (requires Playwright)
126+
pytest tests/test_*.py
127+
128+
# Pre-commit checks
129+
pre-commit run --all-files
130+
```
131+
132+
### Code Quality
133+
- **Linting:** Ruff (configured in pyproject.toml)
134+
- **Formatting:** Ruff format
135+
- **Type checking:** Basic type hints (not enforced with mypy)
136+
- **Spell checking:** Codespell via pre-commit hooks
137+
- **Docstrings:** Google-style convention
138+
139+
### CI/CD Pipeline
140+
- **Integration tests** - On push to main and PRs
141+
- **Unit tests** - On pull requests
142+
- **Deploy workflows** - Separate pipelines for dev, staging, production
143+
- **Search index updates** - Typesense index updates on content changes
144+
145+
## Database Models
146+
147+
### Customer Model (`pcweb/models.py:1`)
148+
- `name` - Customer name
149+
- `email` - Email address
150+
- `phone` - Phone number
151+
- `address` - Physical address
152+
153+
Managed through SQLAlchemy ORM with Alembic migrations in `alembic/versions/`.
154+
155+
## Styling Architecture
156+
157+
### Tailwind CSS v4
158+
- Custom theme in `tailwind_config.py:1`
159+
- Radix UI color palette integration via `tailwind_radix_map.py:1`
160+
- Dark/light mode support
161+
- Responsive design utilities
162+
163+
### Component Styling
164+
- ~262 Python files across pcweb directory
165+
- Extensive use of Tailwind utility classes
166+
- Component library organized in 22 subdirectories
167+
- Custom components inherit from Reflex base classes
168+
169+
### Typography
170+
- **Instrument Sans** - Body text
171+
- **JetBrains Mono** - Code blocks
172+
173+
## Documentation Structure
174+
175+
The site includes comprehensive documentation in `/docs`:
176+
177+
1. **Getting Started** - 11 guides for beginners
178+
2. **UI/Components** - Component usage and API
179+
3. **Database** - Database integration guides
180+
4. **Events** - Event handling documentation
181+
5. **State Management** - State handling patterns
182+
6. **Hosting** - Self-hosted and cloud deployment
183+
7. **Enterprise** - AG Grid, Mantine, React Flow integration
184+
8. **API Reference** - Complete API documentation
185+
186+
Blog posts (29+) cover technical topics and framework updates.
187+
188+
## Common Tasks
189+
190+
### Adding a New Page
191+
1. Create component in `pcweb/pages/[section]/[pagename].py`
192+
2. Define route in `pcweb/route.py:1`
193+
3. Register route in `pcweb/pcweb.py:1`
194+
4. Add to navigation if needed
195+
196+
### Adding Documentation
197+
1. Create markdown file in `docs/[category]/[doc-name].md`
198+
2. Update doc index/navigation in relevant page component
199+
3. Rebuild search index (runs automatically in CI)
200+
201+
### Adding a Blog Post
202+
1. Create markdown file in `blog/[YYYY-MM-DD-title].md`
203+
2. Include frontmatter (title, author, date, description)
204+
3. Post automatically appears in blog index
205+
206+
### Styling Changes
207+
- Global styles: `pcweb/styles/styles.py:1`
208+
- Colors: `pcweb/styles/colors.py:1`
209+
- Tailwind config: `tailwind_config.py:1`
210+
211+
### Database Migrations
212+
```bash
213+
# Create migration
214+
alembic revision --autogenerate -m "description"
215+
216+
# Apply migration
217+
alembic upgrade head
218+
219+
# Rollback
220+
alembic downgrade -1
221+
```
222+
223+
## Environment Variables
224+
225+
Check `rxconfig.py:1` and `.env` for required environment variables:
226+
- Database connection strings
227+
- API keys (OpenAI, Typesense, Loops.so, etc.)
228+
- Deployment configuration
229+
230+
## Build & Deploy
231+
232+
### Local Build
233+
```bash
234+
reflex export
235+
```
236+
237+
### Production Deploy
238+
Automated via GitHub Actions workflows:
239+
- `.github/workflows/deploy-dev.yml:1` - Dev environment
240+
- `.github/workflows/deploy-stg.yml:1` - Staging environment
241+
- `.github/workflows/deploy-prd.yml:1` - Production environment
242+
243+
Cloud configuration in `cloud-prod.yml:1`.
244+
245+
## Key Dependencies
246+
247+
**Core:** reflex, reflex-enterprise (rxe), fastapi, uvicorn
248+
**Database:** sqlalchemy, alembic, psycopg
249+
**Frontend:** tailwindcss, radix-ui (via Reflex)
250+
**APIs:** openai, httpx, aiohttp
251+
**Dev Tools:** pytest, playwright, ruff, pre-commit
252+
**Total:** 31 main dependencies (see `pyproject.toml:1`)
253+
254+
## Architecture Notes
255+
256+
### Reflex Framework
257+
- Python-only full-stack framework
258+
- Compiles to React on frontend
259+
- State management through Python classes
260+
- Event handlers are Python functions
261+
- No JavaScript required for development
262+
263+
### Page Rendering
264+
- Server-side rendering (SSR) support
265+
- Static generation for docs and blog
266+
- Dynamic routes with path parameters
267+
- SEO optimization through meta tags
268+
269+
### Component System
270+
- Reusable components in `pcweb/components/`
271+
- Template system in `pcweb/templates/`
272+
- Style inheritance through Reflex component classes
273+
- Props passed as Python function arguments
274+
275+
## Testing Strategy
276+
277+
### Unit Tests (`tests/`)
278+
- Component rendering tests
279+
- URL routing tests
280+
- Event handler tests
281+
- State management tests
282+
283+
### Integration Tests
284+
- End-to-end with Playwright
285+
- Full user flows (signup, navigation, search)
286+
- Cross-browser testing
287+
288+
### Test Configuration
289+
- `tests/conftest.py:1` - Pytest fixtures
290+
- Test files: `tests/test_*.py`
291+
- Run via `pytest` command
292+
293+
## Getting Help
294+
295+
- **Documentation:** https://reflex.dev/docs
296+
- **Discord:** Community support
297+
- **GitHub Issues:** https://github.com/reflex-dev/reflex-web/issues
298+
- **Main Reflex Repo:** https://github.com/reflex-dev/reflex
299+
300+
## Branch Information
301+
302+
Current branch: `focused-euler`
303+
Main branch: `main`
304+
This is a git worktree (check git status for current location and main repository path)
305+
306+
---
307+
308+
*Last Updated: 2026-02-06*

0 commit comments

Comments
 (0)