kmtnflower/.claude/CLAUDE.md

CLAUDE.md — KMountain Flower Radio Station

Project overview

A three-tier web app for a community radio station: Angular 21 frontend, FastAPI backend, PostgreSQL database. Renders a hero page, about page, broadcast schedule, upcoming events, and a contact form — styled with a warm mountain/nature color palette (blue primary + orange accent on cream). Donations route to an externally configured URL.

Code style

• Components: Standalone only (no NgModules). Every component is a single file with @Component decorator, imports array, and four standard files (.ts, .html, .scss, component).
• Data patterns: Page content (programs, events) is stored in PostgreSQL and served via the FastAPI backend. The frontend uses HTTP services (src/app/services/) to fetch data at runtime. To add or modify content, interact with the API or run seed.py — never hardcode content in components.
• SCSS: All design tokens go in src/styles/_variables.scss. Mixins in _mixins.scss. CSS custom properties exposed in _themes.scss. Components import via @use 'variables' (no relative path needed).
• Routes: Defined in src/app/app.routes.ts using loadComponent() lazy loading. Add new pages here after creating the component.
• TypeScript: Strict mode enabled. Use readonly for constants (config, URLs). Keep data shapes close to their components where used only once.

Architecture

See README.md for a full architecture map. Key files:

• src/app/app.routes.ts — all frontend routing
• src/environments/environment.ts — dev API URL (http://localhost:8000)
• src/environments/environment.prod.ts — prod API URL ('', proxied through Nginx)
• src/styles/_variables.scss — color palette, spacing, breakpoints (change these to re-skin)
• src/styles/_mixins.scss — card-style, button-style, responsive, gradient-text, flowery-border, fade-in
• src/styles/_themes.scss — SCSS → CSS custom property mapping
• docker-compose.dev.yml — dev-sidecar compose for VS Code dev container
• backend/app/main.py — FastAPI entry point (CORS, router registration)
• backend/app/models.py — SQLAlchemy ORM (Show, Event, StationConfig)

Common tasks

• Re-skin: Edit colors in _variables.scss only.
• Add a page: Create component folder → add route in app.routes.ts → add nav link (if needed).
• Update content (dev): Run the API, then use Swagger UI at http://localhost:8000/docs to create/update content.
• Update content (seed): Edit backend/seed.py and restart the API (autoseed runs on empty DB), or hit curl -X POST http://localhost:8000/api/admin/reset to re-seed.
• Run the app (dev): From the backend/ directory, set KMTN_DATABASE_URL=sqlite+aiosqlite:///./kmountain.db, then uvicorn app.main:app --reload + ng serve in parallel. Autoseed populates data on first run.
• Run the app (dev container): Reopen in Container via VS Code.
• Build: ng build → dist/.