docs: describe the system that exists, not the one we started with
The README still opened on "Primary School Compass", a KS2 tool for Wandsworth and Merton served by FastAPI and vanilla JavaScript with Chart.js. Every layer of that sentence is now wrong: coverage is England-wide across KS2, KS4, all-through and post-16, Next.js owns the public UI, and school data comes from dbt-built `marts.*` rather than CSVs loaded at startup. The setup instructions walked a reader into a virtualenv and a CSV import that cannot build the current schema, so following the docs produced an empty database and a wrong mental model at the same time. Replace the narrative docs with two reference documents that were checked against the code: docs/ARCHITECTURE.md for request flow, data ownership, the backend/frontend module boundaries and the real publication sequence, and docs/DEVELOPMENT.md for the checks that actually run, including the container and CI version skew that makes "just run pytest" misleading. The env examples drifted the same way. ALLOWED_ORIGINS is a JSON array, not a comma-separated list; the frontend needs FASTAPI_URL, DATABASE_URL and PAYLOAD_SECRET, none of which were documented; and RATE_LIMIT_BURST, DEFAULT_PAGE_SIZE and MAX_PAGE_SIZE were presented as tuning controls the routes do not consult. Each is now stated as it behaves. MIGRATION_SUMMARY.md keeps its content but gains a banner, because it reads like setup instructions and is not. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016y2J6bs8gbuSJbH18w7Tan
This commit is contained in:
TudorandClaude Opus 5 committed
1 parent
be780ebe13
commit
eaf5e5d180
10 files changed
+377
-996
No files matched your search
+43
-141
@@ -1,156 +1,58 @@
|
||||
# SchoolCompare Next.js Application
|
||||
# SchoolCompare frontend and CMS
|
||||
|
||||
Modern Next.js application for comparing primary school KS2 performance across England.
|
||||
Next.js App Router with React, TypeScript, CSS Modules, Chart.js, Leaflet and
|
||||
Payload CMS. It serves school search, comparisons, rankings, school/place detail
|
||||
pages and editorial content across England.
|
||||
|
||||
## Features
|
||||
Start with the [repository overview](../README.md),
|
||||
[architecture](../docs/ARCHITECTURE.md) and [development checks](../docs/DEVELOPMENT.md).
|
||||
|
||||
- **Server-Side Rendering (SSR)**: Fast initial page loads with pre-rendered content
|
||||
- **Individual School Pages**: Dedicated pages for each school with full SEO optimization
|
||||
- **Side-by-Side Comparison**: Compare up to 5 schools simultaneously
|
||||
- **School Rankings**: Top-performing schools by various metrics
|
||||
- **Interactive Maps**: Leaflet integration for geographic visualization
|
||||
- **Performance Charts**: Chart.js visualizations for historical data
|
||||
- **Responsive Design**: Mobile-first approach with full responsive support
|
||||
- **SEO Optimized**: Dynamic sitemaps, meta tags, and structured data
|
||||
## Source map
|
||||
|
||||
## Tech Stack
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `app/(frontend)/` | Public root layout, server pages and FastAPI proxy |
|
||||
| `app/(payload)/` | Payload root layout, `/admin` and `/cms-api` |
|
||||
| `app/robots.ts`, `app/opengraph-image.tsx`, root icons | Site-wide metadata endpoints |
|
||||
| `components/` | Client views and reusable display components |
|
||||
| `components/school/` | School detail sections |
|
||||
| `lib/api.ts`, `lib/types.ts` | Fetch wrappers and manual school API types |
|
||||
| `lib/schoolSections.ts`, `lib/compareLogic.ts` | Presentation decisions and data preparation |
|
||||
| `context/`, `hooks/` | Comparison state, suggestion state and responsive behaviour |
|
||||
| `collections/`, `blocks/`, `migrations/` | CMS schema and production migrations |
|
||||
| `__tests__/` | Jest and React Testing Library tests |
|
||||
|
||||
- **Framework**: Next.js 16 (App Router)
|
||||
- **Language**: TypeScript 5
|
||||
- **Styling**: CSS Modules + CSS Variables
|
||||
- **State Management**: React Context API + URL state
|
||||
- **Data Fetching**: SWR (client-side) + Next.js fetch (server-side)
|
||||
- **Charts**: Chart.js + react-chartjs-2
|
||||
- **Maps**: Leaflet + react-leaflet
|
||||
- **Testing**: Jest + React Testing Library
|
||||
- **Validation**: Zod
|
||||
Do not introduce a shared `app/layout.tsx`: public pages and Payload have separate
|
||||
root layouts. Keep root metadata files outside the route groups.
|
||||
|
||||
## Getting Started
|
||||
## Data and state
|
||||
|
||||
### Prerequisites
|
||||
Server pages fetch initial data directly from `FASTAPI_URL`. Browser fetches use
|
||||
`/api` by default, forwarded by `app/(frontend)/api/[...path]/route.ts`.
|
||||
`FASTAPI_URL` must include `/api`. See `.env.example` for CMS and API settings.
|
||||
|
||||
- Node.js 24+ (using nvm recommended)
|
||||
- FastAPI backend running on port 8000
|
||||
State uses React hooks/context, URL search parameters and localStorage for the
|
||||
comparison basket. SWR is not installed. Maps use dynamic Leaflet wrappers.
|
||||
Revalidation intervals are configured in fetch wrappers and pages; they vary by
|
||||
resource. Backend reloads do not automatically invalidate every Next.js cache.
|
||||
|
||||
### Installation
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Copy environment variables
|
||||
cp .env.example .env.local
|
||||
|
||||
# Update .env.local with your configuration
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
|
||||
# Open http://localhost:3000
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Build for production
|
||||
```sh
|
||||
npm ci
|
||||
npm run typecheck
|
||||
npm test -- --runInBand
|
||||
npm run build
|
||||
|
||||
# Start production server
|
||||
npm start
|
||||
```
|
||||
|
||||
### Testing
|
||||
`test:watch` and `test:coverage` are also available. There is no `lint` script.
|
||||
A running application needs the backend/data environment described in the
|
||||
[development guide](../docs/DEVELOPMENT.md).
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
npm test
|
||||
After CMS field or editor changes, run `npm run generate:importmap`. Keep
|
||||
`payload-types.ts` generated from the CMS schema rather than editing it by hand.
|
||||
The build must work without a database connection; avoid module-scope CMS queries
|
||||
and DB-backed `generateStaticParams` functions.
|
||||
|
||||
# Run tests in watch mode
|
||||
npm run test:watch
|
||||
|
||||
# Run tests with coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Linting
|
||||
|
||||
```bash
|
||||
# Run ESLint
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
nextjs-app/
|
||||
├── app/ # App Router pages
|
||||
│ ├── layout.tsx # Root layout
|
||||
│ ├── page.tsx # Home page
|
||||
│ ├── compare/ # Compare page
|
||||
│ ├── rankings/ # Rankings page
|
||||
│ ├── school/[urn]/ # Individual school pages
|
||||
│ ├── sitemap.ts # Dynamic sitemap
|
||||
│ └── robots.ts # Robots.txt
|
||||
├── components/ # React components
|
||||
│ ├── SchoolCard.tsx # School card component
|
||||
│ ├── FilterBar.tsx # Search/filter controls
|
||||
│ ├── ComparisonView.tsx # Comparison interface
|
||||
│ ├── RankingsView.tsx # Rankings table
|
||||
│ └── ...
|
||||
├── lib/ # Utility libraries
|
||||
│ ├── api.ts # API client
|
||||
│ ├── types.ts # TypeScript types
|
||||
│ └── utils.ts # Helper functions
|
||||
├── hooks/ # Custom React hooks
|
||||
├── context/ # React Context providers
|
||||
├── styles/ # Global styles
|
||||
├── public/ # Static assets
|
||||
└── __tests__/ # Test files
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `NEXT_PUBLIC_API_URL` | Public API endpoint (client-side) | `http://localhost:8000/api` |
|
||||
| `FASTAPI_URL` | Server-side API endpoint | `http://localhost:8000/api` |
|
||||
| `NODE_ENV` | Environment mode | `development` |
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
- **Server-Side Rendering**: Initial HTML rendered on server
|
||||
- **Static Generation**: Where possible, pages are pre-generated
|
||||
- **Image Optimization**: Next.js Image component with AVIF/WebP support
|
||||
- **Code Splitting**: Automatic route-based code splitting
|
||||
- **Dynamic Imports**: Heavy components loaded on demand
|
||||
- **API Caching**: Configurable revalidation for data fetching
|
||||
- **Bundle Optimization**: Tree shaking and minification
|
||||
- **Compression**: Gzip compression enabled
|
||||
|
||||
## SEO Features
|
||||
|
||||
- **Dynamic Meta Tags**: Generated per page with Next.js Metadata API
|
||||
- **Open Graph**: Social media optimization
|
||||
- **JSON-LD**: Structured data for search engines
|
||||
- **Sitemap**: Auto-generated from database
|
||||
- **Robots.txt**: Search engine crawling rules
|
||||
- **Canonical URLs**: Duplicate content prevention
|
||||
|
||||
## Browser Support
|
||||
|
||||
- Chrome (latest)
|
||||
- Firefox (latest)
|
||||
- Safari (latest)
|
||||
- Edge (latest)
|
||||
|
||||
## License
|
||||
|
||||
Proprietary - SchoolCompare
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions, please contact the development team.
|
||||
See [publishing](docs/PUBLISHING.md) for CMS operations and
|
||||
[deployment](../docs/DEPLOY.md) for staging and production promotion.
|
||||
Reference in new issue
Block a user