Skip to content

Commit 9bcf8e2

Browse files
committed
Add project documentation, assets, and navigation updates
- Add CLAUDE.md with project setup and development instructions - Add memray-logo.png asset for branding - Configure GitHub image domains in next.config.ts - Add About page to navigation header
1 parent 14687c4 commit 9bcf8e2

File tree

4 files changed

+118
-2
lines changed

4 files changed

+118
-2
lines changed

CLAUDE.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
CPython Memory Tracker - A memory benchmarking and analysis tool for CPython development. It tracks memory usage patterns across different commits and build configurations.
8+
9+
Architecture: Three-tier web application with FastAPI backend, Next.js frontend, and Python worker CLI.
10+
11+
## Development Commands
12+
13+
### Full Setup
14+
```bash
15+
make setup # Install dependencies + initialize database
16+
```
17+
18+
### Running Development Servers
19+
```bash
20+
make dev # Start both frontend (port 9002) and backend (port 8000)
21+
make dev-frontend # Frontend only
22+
make dev-backend # Backend only
23+
```
24+
25+
### Testing & Code Quality
26+
```bash
27+
make test # Run backend tests (pytest)
28+
npm run lint # Frontend linting (run in frontend/ directory)
29+
npm run typecheck # TypeScript type checking (run in frontend/ directory)
30+
```
31+
32+
### Database Management
33+
```bash
34+
make init-db # Initialize database schema
35+
make populate-db # Add mock data
36+
make reset-db # Drop and recreate with fresh data
37+
```
38+
39+
### Production Build
40+
```bash
41+
make build # Build frontend for production
42+
```
43+
44+
## Architecture & Structure
45+
46+
### Backend (FastAPI + SQLite)
47+
- `/backend/app/` - Main application code
48+
- `/backend/app/routers/` - API endpoints (benchmarks, commits, runs, upload, admin)
49+
- `/backend/app/models.py` - SQLAlchemy database models
50+
- `/backend/app/schemas.py` - Pydantic validation schemas
51+
- Authentication: OAuth via GitHub (`/backend/app/oauth.py`)
52+
53+
### Frontend (Next.js + TypeScript)
54+
- `/frontend/src/app/` - Next.js app router pages
55+
- `/frontend/src/components/` - Reusable UI components
56+
- `/frontend/src/hooks/` - Custom React hooks (useApi, useChartData)
57+
- `/frontend/src/lib/api.ts` - API client functions
58+
- UI: Radix UI components with Tailwind CSS
59+
- Data visualization: Recharts library
60+
61+
### Worker (Python CLI)
62+
- `/worker/src/memory_tracker_worker/` - Main worker code
63+
- `/worker/src/memory_tracker_worker/benchmarks/` - Benchmark implementations
64+
- Runs memory benchmarks on CPython commits using Memray
65+
66+
## Key API Patterns
67+
68+
### Backend API Structure
69+
- RESTful endpoints under `/api/v1/`
70+
- Admin endpoints require authentication under `/api/v1/admin/`
71+
- File uploads handled at `/api/v1/upload/{benchmark_id}`
72+
- Health check at `/health`
73+
74+
### Frontend Data Fetching
75+
- Uses TanStack Query (React Query) for caching and state management
76+
- API client in `/frontend/src/lib/api.ts`
77+
- Custom hooks in `/frontend/src/hooks/useApi.ts`
78+
79+
## Testing
80+
81+
### Running Tests
82+
```bash
83+
cd backend && python -m pytest tests/ -v # Backend tests
84+
```
85+
86+
### Test Structure
87+
- Backend: pytest with pytest-asyncio for async tests
88+
- Frontend: TypeScript type checking serves as primary validation
89+
90+
## Environment Configuration
91+
92+
Backend requires `.env` file with:
93+
- `DATABASE_URL` - SQLite connection string
94+
- `SECRET_KEY` - Session secret
95+
- `GITHUB_CLIENT_ID` - OAuth client ID
96+
- `GITHUB_CLIENT_SECRET` - OAuth client secret
97+
98+
Frontend environment variables in `.env.local`:
99+
- `NEXT_PUBLIC_API_URL` - Backend API URL
100+
101+
## Database Schema
102+
103+
Key models:
104+
- `Commit` - CPython commit information
105+
- `Binary` - Different Python build configurations
106+
- `Environment` - Runtime environments
107+
- `Benchmark` - Individual benchmark definitions
108+
- `BenchmarkRun` - Execution results with memory stats
109+
- `User`, `Token` - Authentication and API access

frontend/next.config.ts

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ const nextConfig: NextConfig = {
1616
port: '',
1717
pathname: '/**',
1818
},
19+
{
20+
protocol: 'https',
21+
hostname: 'github.com',
22+
port: '',
23+
pathname: '/**',
24+
},
1925
],
2026
},
2127
output: 'standalone',

frontend/public/memray-logo.png

208 KB
Loading

frontend/src/components/layout/Header.tsx

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ import {
1010
Moon,
1111
GitCompare,
1212
GitBranch,
13-
} from 'lucide-react'; // Removed UploadCloud
13+
Info,
14+
} from 'lucide-react';
1415
import { useTheme } from 'next-themes';
1516
import { Button } from '@/components/ui/button';
1617
import { Sheet, SheetContent, SheetTrigger } from '@/components/ui/sheet';
@@ -23,7 +24,7 @@ const navItems = [
2324
{ href: '/version-comparison', label: 'Version Comparison', icon: GitBranch },
2425
{ href: '/diff', label: 'Inspect Run Results', icon: GitCompareArrows },
2526
{ href: '/binaries', label: 'Binary Configurations', icon: ListChecks },
26-
// { href: '/upload', label: 'Upload Data', icon: UploadCloud }, // Removed
27+
{ href: '/about', label: 'About', icon: Info },
2728
];
2829

2930
export default function Header() {

0 commit comments

Comments
 (0)