251 lines
9.9 KiB
Markdown
251 lines
9.9 KiB
Markdown
# KMountain Flower Radio Station
|
|
|
|
A three-tier web application for a community radio station: Angular 21 frontend, FastAPI backend, PostgreSQL database.
|
|
|
|
Renders a hero page, about page, broadcast schedule, donation tiers, upcoming events, and a contact form — styled with a warm mountain/nature aesthetic.
|
|
|
|
## Quick Start
|
|
|
|
### Option A — Docker Compose (recommended)
|
|
|
|
```bash
|
|
# Start all services
|
|
docker compose up --build
|
|
|
|
# Seed the database (first run only)
|
|
docker compose exec api python seed.py
|
|
```
|
|
|
|
Open [http://localhost:4200](http://localhost:4200).
|
|
|
|
### Option B — Manual (frontend + backend separately)
|
|
|
|
```bash
|
|
# Database
|
|
createdb kmountain
|
|
export KMTN_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/kmountain
|
|
|
|
# Backend
|
|
cd backend && pip install -r requirements.txt
|
|
uvicorn app.main:app --reload
|
|
|
|
# Frontend (new terminal)
|
|
npm install && ng serve
|
|
```
|
|
|
|
Open [http://localhost:4200](http://localhost:4200) and ensure the backend is running on [http://localhost:8000](http://localhost:8000).
|
|
|
|
## Prerequisites
|
|
|
|
| Requirement | Version | Notes |
|
|
|---|---|---|
|
|
| Docker + Docker Compose | 24+ | For the Docker Compose path |
|
|
| Node.js | 20+ | For manual frontend development |
|
|
| npm | 11+ | |
|
|
| Python | 3.12+ | For manual backend development |
|
|
| PostgreSQL | 16+ | For manual backend development (Docker handles it) |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌──────────────┐
|
|
│ Browser │
|
|
│ :4200 / :80│
|
|
└──────┬───────┘
|
|
│
|
|
┌────────────┴────────────┐
|
|
│ │
|
|
┌────▼─────┐ ┌──────▼─────┐
|
|
│ Nginx │ /api/* │ FastAPI │
|
|
│ (static) │─ proxy ──▶ │ :8000 │
|
|
└────┬─────┘ └──────┬─────┘
|
|
│ │
|
|
┌────▼─────┐ ┌──────▼─────┐
|
|
│ Angular 21│ │ PostgreSQL │
|
|
│ SPA │ │ :5432 │
|
|
└──────────┘ └────────────┘
|
|
```
|
|
|
|
**Three tiers:**
|
|
|
|
1. **Frontend** — Angular 21 SPA built via multi-stage Dockerfile and served by Nginx. In production, Nginx serves the static files and proxies `/api/*` requests to the backend. In development, both run on separate ports and the browser talks directly to both.
|
|
2. **Backend** — Python FastAPI with async SQLAlchemy. Provides CRUD REST endpoints for programs (broadcast schedule), events (upcoming events), and donation tiers. Auto-generates Swagger/OpenAPI docs at `/docs`.
|
|
3. **Database** — PostgreSQL 16. Schema contains three tables: `programs`, `events`, `donation_tiers`. Initial data is loaded via [seed.py](backend/seed.py).
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── docker-compose.yml # 3-service stack (db, api, frontend)
|
|
├── Dockerfile # Multi-stage: Angular build → Nginx serve
|
|
├── nginx.conf # Static files + /api/* proxy
|
|
├── .env.example # Environment variable template
|
|
├── .devcontainer/ # VS Code dev container
|
|
│
|
|
├── src/ # Angular 21 frontend
|
|
│ ├── app/ # Standalone components
|
|
│ │ ├── app.routes.ts # Lazy-loaded route map
|
|
│ │ ├── hero/ about/ schedule/ donate/ events/ contact/ navbar/ footer/
|
|
│ │ ├── services/ # HTTP services (program, event, tier)
|
|
│ │ └── interfaces/ # TypeScript types (Program, Event, Tier)
|
|
│ ├── environments/ # dev/prod config (apiBaseUrl)
|
|
│ └── styles/ # SCSS design tokens
|
|
│ ├── _variables.scss # Colors, spacing, breakpoints
|
|
│ ├── _mixins.scss # Card, button, responsive mixins
|
|
│ └── _themes.scss # SCSS → CSS custom properties
|
|
│
|
|
└── backend/ # FastAPI backend
|
|
├── Dockerfile # Python gunicorn/uvicorn
|
|
├── requirements.txt
|
|
├── seed.py # Initial data for all models
|
|
└── app/
|
|
├── main.py # FastAPI app, CORS, router registration
|
|
├── config.py # ENV-based settings (KMTN_* prefix)
|
|
├── database.py # async engine + session factory
|
|
├── models.py # SQLAlchemy ORM (Program, Event, DonationTier)
|
|
├── schemas.py # Pydantic schemas (Create/Update/Response)
|
|
└── api/
|
|
├── programs.py # CRUD /api/programs
|
|
├── events.py # CRUD /api/events
|
|
└── tiers.py # CRUD /api/tiers
|
|
```
|
|
|
|
## Local Development
|
|
|
|
### Docker Compose
|
|
|
|
```bash
|
|
docker compose up --build # Start all services
|
|
docker compose exec api python seed.py # Seed database (first run)
|
|
docker compose logs -f api # Stream backend logs
|
|
docker compose down # Stop and remove containers
|
|
```
|
|
|
|
The `pgdata` volume persists the database across container restarts.
|
|
|
|
### Manual Development
|
|
|
|
Run all three layers in parallel:
|
|
|
|
```bash
|
|
# 1. Database (install PostgreSQL 16 locally)
|
|
createdb kmountain
|
|
|
|
# 2. Backend (new terminal)
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
export KMTN_DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/kmountain
|
|
export KMTN_CORS_ORIGINS='["http://localhost:4200"]'
|
|
uvicorn app.main:app --reload
|
|
|
|
# 3. Frontend (another terminal)
|
|
npm install
|
|
ng serve
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Where | Description |
|
|
|---|---|---|---|
|
|
| `KMTN_DATABASE_URL` | `postgresql+asyncpg://postgres:postgres@localhost:5432/kmountain` | [backend/app/config.py](backend/app/config.py) | Async PostgreSQL connection string |
|
|
| `KMTN_CORS_ORIGINS` | `["http://localhost:4200"]` | [backend/app/config.py](backend/app/config.py) | CORS allowlist (JSON array) |
|
|
| `apiBaseUrl` | `http://localhost:8000` (dev) / `''` (prod) | [src/environments/](src/environments/) | Where the Angular app finds the API |
|
|
|
|
Environment variables are prefixed with `KMTN_` in the backend. For production, set `KMTN_DATABASE_URL` to your managed PostgreSQL connection and update `KMTN_CORS_ORIGINS` to your actual domain.
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Frontend (produces dist/radio-station/browser/)
|
|
ng build --configuration production
|
|
|
|
# Backend Docker image
|
|
docker build -t kmountain-api -f backend/Dockerfile backend/
|
|
|
|
# Full production stack
|
|
docker compose up --build -d
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
ng test # Angular + Vitest
|
|
```
|
|
|
|
The backend API is self-documented at [http://localhost:8000/docs](http://localhost:8000/docs) (Swagger UI). Run `docker compose exec api python seed.py` and visit that URL to interactively test endpoints.
|
|
|
|
## API Reference
|
|
|
|
The backend exposes CRUD endpoints for three models:
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| `GET` | `/api/programs` | List all programs (`?day=1..7` to filter by day of week) |
|
|
| `GET` | `/api/programs/:id` | Single program |
|
|
| `POST` | `/api/programs` | Create program |
|
|
| `PUT` | `/api/programs/:id` | Update program |
|
|
| `DELETE` | `/api/programs/:id` | Delete program |
|
|
| `GET` | `/api/events` | List events (`?active=true` to filter active events) |
|
|
| `GET` | `/api/events/:id` | Single event |
|
|
| `POST` | `/api/events` | Create event |
|
|
| `PUT` | `/api/events/:id` | Update event |
|
|
| `DELETE` | `/api/events/:id` | Delete event |
|
|
| `GET` | `/api/tiers` | List donation tiers (ordered by `display_order`) |
|
|
| `GET` | `/api/tiers/:id` | Single tier |
|
|
| `POST` | `/api/tiers` | Create tier |
|
|
| `PUT` | `/api/tiers/:id` | Update tier |
|
|
| `DELETE` | `/api/tiers/:id` | Delete tier |
|
|
|
|
Full interactive API docs at [http://localhost:8000/docs](http://localhost:8000/docs).
|
|
|
|
## Deployment
|
|
|
|
### Production (Docker Compose on a VPS)
|
|
|
|
```bash
|
|
# 1. Clone repo on server
|
|
git clone <repo-url> kmountain
|
|
cd kmountain
|
|
|
|
# 2. Edit docker-compose.yml
|
|
# - Change POSTGRES_PASSWORD to a strong value
|
|
# - Update KMTN_CORS_ORIGINS to your domain
|
|
# - Optionally set KMTN_DATABASE_URL to a managed PostgreSQL
|
|
|
|
# 3. Build and start
|
|
docker compose up --build -d
|
|
|
|
# 4. Seed the database
|
|
docker compose exec api python seed.py
|
|
```
|
|
|
|
### Production hardening checklist
|
|
|
|
- [ ] Change the default `POSTGRES_PASSWORD` in [docker-compose.yml](docker-compose.yml)
|
|
- [ ] Update `KMTN_CORS_ORIGINS` to your actual domain (not `localhost`)
|
|
- [ ] Set `KMTN_DATABASE_URL` to a managed PostgreSQL connection (RDS, Cloud SQL, etc.)
|
|
- [ ] Add a reverse proxy (Caddy, Traefik) in front of Nginx for HTTPS
|
|
- [ ] Set up log rotation for Docker containers
|
|
- [ ] Configure Docker image registry and push/pull workflow
|
|
|
|
## Development Tools
|
|
|
|
- **Dev container** — Open the repo in VS Code → "Reopen in Container" for a pre-configured environment with Angular CLI, Node.js, Python 3, and Git ([.devcontainer/](.devcontainer/)).
|
|
- **VS Code workspace** — [workspace file](web_app.code-workspace) in the repo root configures both Angular and Python extensions.
|
|
- **Prettier** — Run `npx prettier --write .` to format the codebase.
|
|
- **Prettier config** — [**.prettierrc**](.prettierrc) (100 char width, single quotes, Angular HTML parser).
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| Frontend | Angular 21 (standalone components, signals-ready) |
|
|
| Backend | FastAPI 0.115, Python 3.12 |
|
|
| Database | PostgreSQL 16 (async via SQLAlchemy 2.0) |
|
|
| Styling | SCSS with design tokens (variables → mixins → CSS custom properties) |
|
|
| Routing | Angular Router (lazy loaded) + Nginx SPA fallback |
|
|
| HTTP | RxJS observables (frontend → FastAPI) |
|
|
| Containers | Docker Compose (3 services: db, api, frontend) |
|
|
| CI/CD | _(not yet configured)_ |
|
|
| Testing | Vitest (via Angular CLI) |
|