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 — Dev Container (recommended)

Open the repo in VS Code and click Reopen in Container (or run Dev Containers: Reopen in Container from the command palette). The dev container starts both the backend (port 8000) and frontend (port 4200) automatically.

Open http://localhost:4200.

Option B — Manual (frontend + backend separately)

# Backend (uses SQLite for local dev — no database server needed)
cd backend
pip install -r requirements.txt
export KMTN_DATABASE_URL="sqlite+aiosqlite:///./kmountain.db"
uvicorn app.main:app --reload

# Frontend (new terminal)
npm install && ng serve

Open http://localhost:4200 and ensure the backend is running on http://localhost:8000.

Prerequisites

Requirement	Version	Notes
Node.js	20+	For frontend development
npm	11+
Python	3.12+	For backend development
PostgreSQL	16+	For production only (dev uses SQLite)

Architecture

                    ┌──────────────┐
                    │    Browser   │
                    │   :4200 / :80│
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              │                         │
         ┌────▼─────┐            ┌──────▼─────┐
         │  Nginx   │   /api/*   │  FastAPI   │
         │ (static) │─ proxy ──▶ │  :8000     │
         └──────────┘            └──────┬─────┘
                                        │
                                 ┌──────▼─────┐
                                 │ PostgreSQL │
                                 │   :5432    │
                                 └────────────┘

Three tiers:

1. Frontend — Angular 21 SPA. In production, served by Nginx. In development, served by the Angular dev server on port 4200.
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. Local development uses SQLite for convenience.

Project Structure

.
├── docker-compose.dev.yml      # Dev-sidecar compose (dev container)
├── .devcontainer/              # VS Code dev container
│   ├── Dockerfile              # Alpine Python 3.12 + Node.js + Angular CLI
│   └── devcontainer.json       # Dev container config
│
├── 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
    ├── 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

Dev Container (recommended)

Open the repo in VS Code → Reopen in Container. The dev container starts both services automatically. See .devcontainer/ for the configuration.

Manual Development

Run both layers in parallel — development uses SQLite (no database server needed):

# 1. Backend (new terminal)
cd backend
pip install -r requirements.txt
export KMTN_DATABASE_URL="sqlite+aiosqlite:///./kmountain.db"
export KMTN_CORS_ORIGINS='["http://localhost:4200"]'
uvicorn app.main:app --reload

# 2. Frontend (another terminal)
npm install
ng serve

The database auto-seeds on first startup. To reset and re-seed at any time:

curl -X POST http://localhost:8000/api/admin/reset

Configuration

Variable	Default	Where	Description
KMTN_DATABASE_URL	postgresql+asyncpg://... (prod) / sqlite+aiosqlite:///./kmountain.db (dev)	backend/app/config.py	Database connection string
KMTN_CORS_ORIGINS	["http://localhost:4200"]	backend/app/config.py	CORS allowlist (JSON array)
KMTN_ENV	development	backend/app/config.py	Set to production to disable admin endpoints
apiBaseUrl	http://localhost:8000 (dev) / '' (prod)	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

# Frontend (produces dist/radio-station/browser/)
ng build --configuration production

For production deployment, serve the built static files with Nginx and run the backend behind it.

Testing

ng test              # Angular + Vitest

The backend API is self-documented at http://localhost:8000/docs (Swagger UI). The database auto-seeds on first startup — 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.

Deployment

Production

For production, you'll need to set up:

• A PostgreSQL database (managed or self-hosted)
• The FastAPI backend (gunicorn/uvicorn)
• Nginx to serve the Angular build and proxy /api/* to the backend

# 1. Build the frontend
ng build --configuration production

# 2. Configure the backend
export KMTN_DATABASE_URL="postgresql+asyncpg://user:pass@host:5432/kmountain"
export KMTN_CORS_ORIGINS='["https://yourdomain.com"]'
export KMTN_ENV="production"

# 3. Start the backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 4. Serve the frontend with Nginx (or your preferred web server),
#    pointing /api/* requests to http://localhost:8000

The database auto-seeds on first startup.

Production hardening checklist

• Use a managed PostgreSQL database (RDS, Cloud SQL, etc.)
• Update KMTN_CORS_ORIGINS to your actual domain (not localhost)
• Set KMTN_ENV="production" to disable admin endpoints
• Add a reverse proxy (Caddy, Traefik) in front of Nginx for HTTPS
• Set up log rotation
• Configure a process manager (systemd, PM2) for the backend

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/).
• VS Code workspace — workspace file in the repo root configures both Angular and Python extensions.
• Prettier — Run npx prettier --write . to format the codebase.
• Prettier config — .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	Dev container (VS Code Remote - Containers)
CI/CD	(not yet configured)
Testing	Vitest (via Angular CLI)