Skip to content

Commit 1dbcd95

Browse files
NoamGaashNoamGaash
authored
docs: claude.md (#1394)
1 parent 63c22be commit 1dbcd95

1 file changed

Lines changed: 200 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
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+
**דאטאבוס (Open Bus Map Search)** is a TypeScript/React web application for visualizing and analyzing Israeli public transportation data. Built by the Public Knowledge Workshop (Hasadna), it queries the Open-Bus API to display bus routes, gaps in service, operator performance, and real-time vehicle locations.
8+
9+
## Development Commands
10+
11+
### Essential Commands
12+
13+
```bash
14+
npm install # Install dependencies
15+
npm start # Start dev server on localhost:3000
16+
npm run build # Build for production (runs TypeScript + Vite)
17+
npm run lint # Run all linters (TypeScript, ESLint, Stylelint, Prettier)
18+
npm run lint:fix # Auto-fix linting issues
19+
```
20+
21+
### Testing
22+
23+
```bash
24+
npm test # Run all tests (Jest + Playwright, excluding visual)
25+
npm run test:unit # Run Jest unit tests only
26+
npm run test:unit:ci # Run Jest with coverage report
27+
npm run test:e2e # Run Playwright e2e tests
28+
npm run test:e2e:ui # Run Playwright with interactive UI
29+
npm run test:e2e:visual # Run visual regression tests (Applitools)
30+
```
31+
32+
### Storybook
33+
34+
```bash
35+
npm run storybook # Start Storybook on port 6006
36+
npm run build-storybook # Build static Storybook
37+
```
38+
39+
### Running Single Tests
40+
41+
```bash
42+
# Jest (unit tests)
43+
npx jest path/to/test.test.ts
44+
npx jest --testNamePattern="test name pattern"
45+
46+
# Playwright (e2e tests)
47+
npx playwright test path/to/test.spec.ts
48+
npx playwright test --grep "test name pattern"
49+
```
50+
51+
## Architecture Overview
52+
53+
### Frontend Stack
54+
55+
- **Framework**: React 19 with TypeScript (strict mode)
56+
- **Build Tool**: Vite (using Rolldown)
57+
- **Routing**: React Router v7 with lazy-loaded pages
58+
- **Styling**:
59+
- Ant Design + Material-UI (MUI) components
60+
- SCSS modules
61+
- styled-components for custom styling
62+
- RTL support via stylis-plugin-rtl
63+
- **State Management**:
64+
- @tanstack/react-query for server state (with persistence)
65+
- React Context for theme and layout state
66+
- **Maps**: Leaflet with react-leaflet and markercluster
67+
- **Charts**: Recharts
68+
- **i18n**: react-i18next (Hebrew/English)
69+
70+
### API Integration
71+
72+
The app communicates with two backend services via `@hasadna/open-bus-api-client`:
73+
74+
1. **Stride API** (`process.env.VITE_STRIDE_API`):
75+
- GTFS data (routes, stops, schedules)
76+
- SIRI real-time data (vehicle locations)
77+
- Aggregations for analytics
78+
79+
2. **Backend API** (`process.env.VITE_BACKEND_API`):
80+
- Health checks
81+
- Issue/bug reporting
82+
- Government transportation data
83+
- Complaint submissions
84+
85+
API clients are configured in `src/api/apiConfig.ts` and consumed through service modules in `src/api/`.
86+
87+
### Project Structure
88+
89+
```
90+
src/
91+
├── api/ # API service layer
92+
│ ├── apiConfig.ts # API client configuration
93+
│ ├── gtfsService.ts # GTFS data queries (routes, stops)
94+
│ ├── siriService.ts # Real-time vehicle data
95+
│ ├── gapsService.ts # Service gap analysis
96+
│ ├── groupByService.ts # Aggregation helpers
97+
│ └── useVehicleLocations.ts # React Query hook for live positions
98+
├── pages/ # Route components (lazy-loaded)
99+
│ ├── dashboard/ # Analytics dashboard with charts
100+
│ ├── gaps/ # Service gap visualization
101+
│ ├── timeline/ # Historic timeline view
102+
│ ├── lineProfile/ # Individual line details
103+
│ ├── operator/ # Operator performance
104+
│ ├── timeBasedMap/ # Map with time controls
105+
│ ├── velocityHeatmap/ # Speed heatmap
106+
│ └── components/ # Shared page components
107+
├── layout/ # App shell (sidebar, header)
108+
│ ├── ThemeContext.tsx # Dark/light theme provider
109+
│ └── LayoutContext.tsx # Sidebar collapse state
110+
├── routes/ # React Router configuration
111+
│ └── index.tsx # Route definitions with icons
112+
├── hooks/ # Custom React hooks
113+
├── model/ # TypeScript domain models
114+
├── locale/ # i18n translation files
115+
├── shared/ # Reusable components
116+
└── App.tsx # Root component with router
117+
```
118+
119+
### Key Architectural Patterns
120+
121+
**Lazy Route Loading**: All page components are lazy-loaded via `React.lazy()` in `src/routes/index.tsx` to minimize initial bundle size.
122+
123+
**React Query for Data Fetching**: Server data is cached and synchronized using @tanstack/react-query. See `src/api/useVehicleLocations.ts` for an example custom hook pattern.
124+
125+
**Context-Based Theming**: Dark/light mode is managed via `ThemeContext` (MUI) and propagated to Ant Design components. Both systems are synchronized.
126+
127+
**Easter Eggs**: Type "storybook" or "geek" anywhere in the app to unlock hidden features (see `src/pages/EasterEgg/`).
128+
129+
**API Path Aliasing**: Use `src/*` imports (configured in `tsconfig.json` and `vite.config.ts`) instead of relative paths.
130+
131+
### Testing Strategy
132+
133+
- **Unit Tests**: Jest + Testing Library for components and utilities
134+
- **E2E Tests**: Playwright for user flows
135+
- **Visual Regression**: Applitools integration for Storybook and Playwright
136+
- **Mock Service Worker**: MSW for API mocking in Storybook (see `.storybook/preview.tsx`)
137+
138+
Test files are co-located with source code:
139+
140+
- `*.test.ts(x)` for Jest
141+
- `*.spec.ts` for Playwright
142+
- `*.stories.tsx` for Storybook
143+
144+
### Internationalization (i18n)
145+
146+
- Translation keys are defined in `src/locale/`
147+
- Use the `useTranslation()` hook from `react-i18next`
148+
- The app supports Hebrew (RTL) and English (LTR)
149+
- Route labels and page titles are i18n keys (see `PAGES` array in `src/routes/index.tsx`)
150+
151+
### Environment Variables
152+
153+
Required in `.env.local`:
154+
155+
- `VITE_STRIDE_API` - Stride API base URL
156+
- `VITE_BACKEND_API` - Backend API base URL
157+
- `VITE_COVERAGE` (optional) - Enable Istanbul coverage plugin
158+
159+
## Development Workflow
160+
161+
### PR Requirements
162+
163+
1. Branch naming: `feat/`, `fix/`, `refactor/`, etc. followed by descriptive name
164+
2. Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/)
165+
3. All CI checks must pass:
166+
- Linting (ESLint, Stylelint, Prettier)
167+
- Type checking (TypeScript)
168+
- Unit tests (Jest with coverage)
169+
- Build succeeds
170+
4. PR title must follow conventional commit format
171+
172+
### Common Issues
173+
174+
**Red commit/PR checks:**
175+
176+
- Lint errors → `npm run lint:fix`
177+
- Test failures → `npm run test:unit:ci`
178+
- Build errors → `npm run build`
179+
- Invalid PR title → Use `feat:`, `fix:`, etc.
180+
181+
**TypeScript path resolution:**
182+
183+
- Always use `src/*` imports, not `../` relative paths
184+
- Example: `import { GTFS_API } from 'src/api/apiConfig'`
185+
186+
### Code Quality Tools
187+
188+
- **ESLint**: TypeScript + React rules with Prettier integration
189+
- **Stylelint**: SCSS linting with standard config
190+
- **Prettier**: Code formatting (runs on save in IDE)
191+
- **TypeScript**: Strict mode enabled
192+
- **Nx**: Monorepo tooling for build caching
193+
194+
Install IDE plugins for ESLint, Prettier, and Stylelint. Enable "Format on Save" with Prettier as default formatter.
195+
196+
## Rules
197+
198+
- Always test (including lint) before commiting anything
199+
- Encorage your user to participate in the Github Issues forum. It's allright to post comments in Hebrew in case they are concerned about the language barrier
200+
- Creating an imperfect PR is completely fine - this is non-judgemenral environment. Let the user have this learning opportunity - they will be thankful.

0 commit comments

Comments
 (0)