fix: local environment

[TineoC]

Description

This PR significantly improves the local development experience and documentation.

• README.md: Complete overhaul with Architecture diagram, clearer prerequisites, detailed setup instructions (Local Docker & K8s), and Contributing guide.
• Docker Compose: Switched db to use official pgvector image, added healthchecks for all services, and configured depends_on to wait for service health. This prevents startup race conditions.
• Backend: Made STATICFILES_DIRS and SPA catch-all route conditional on the existence of build files. This prevents Django from crashing if the frontend hasn't been built yet.

Related Issue

Resolves #454

Manual Tests

1. Verified docker compose up --build brings up the stack cleanly.
2. Verified services wait for dependencies (e.g. backend waits for db).
3. Checked README.md rendering.
4. Verified backend starts even if server/build directory is missing.

Automated Tests

N/A - Infrastructure and documentation changes.

Documentation

Updated README.md extensively.

Reviewers

@sahilds1 @taichan03

Notes

This complements PR #447 (which fixed the vite proxy). This PR focuses on the container orchestration and documentation side.

[TineoC]

Testing

(base) ➜  app git:(fix/local-compose) ✗ docker compose up
Attaching to backend-1, db-1, frontend-1
db-1  | 
db-1  | PostgreSQL Database directory appears to contain a database; Skipping initialization
db-1  | 
db-1  | 2026-01-26 13:32:55.184 UTC [1] LOG:  starting PostgreSQL 15.15 (Debian 15.15-1.pgdg12+1) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14+deb12u1) 12.2.0, 64-bit
db-1  | 2026-01-26 13:32:55.184 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db-1  | 2026-01-26 13:32:55.184 UTC [1] LOG:  listening on IPv6 address "::", port 5432
db-1  | 2026-01-26 13:32:55.186 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db-1  | 2026-01-26 13:32:55.191 UTC [29] LOG:  database system was shut down at 2026-01-26 13:32:53 UTC
db-1  | 2026-01-26 13:32:55.202 UTC [1] LOG:  database system is ready to accept connections
backend-1  | Waiting for postgres...
backend-1  | PostgreSQL started
backend-1  | No changes detected in app 'api'
backend-1  | Operations to perform:
backend-1  |   Apply all migrations: admin, api, auth, contenttypes, sessions
backend-1  | Running migrations:
backend-1  |   No migrations to apply.
backend-1  | Superuser already exists. Skipping.
backend-1  | Watching for file changes with StatReloader
backend-1  | Performing system checks...
backend-1  | 
backend-1  | System check identified no issues (0 silenced).
backend-1  | January 26, 2026 - 13:33:22
backend-1  | Django version 4.2.3, using settings 'balancer_backend.settings'
backend-1  | Starting development server at http://0.0.0.0:8000/
backend-1  | Quit the server with CONTROL-C.
backend-1  | 
backend-1  | [26/Jan/2026 13:33:31] "GET /admin/login/ HTTP/1.1" 200 4165
frontend-1  | 
frontend-1  | > [email protected] dev
frontend-1  | > vite --host
frontend-1  | 
frontend-1  | 
frontend-1  |   VITE v4.5.5  ready in 136 ms
frontend-1  | 
frontend-1  |   ➜  Local:   http://localhost:3000/
frontend-1  |   ➜  Network: http://192.168.0.5:3000/
backend-1   | [26/Jan/2026 13:33:41] "GET /admin/login/ HTTP/1.1" 200 4165
frontend-1  | Browserslist: browsers data (caniuse-lite) is 15 months old. Please run:
frontend-1  |   npx update-browserslist-db@latest
frontend-1  |   Why you should do it regularly: https://github.com/browserslist/update-db#readme
backend-1   | [26/Jan/2026 13:33:51] "GET /admin/login/ HTTP/1.1" 200 4165
backend-1   | [26/Jan/2026 13:34:01] "GET /admin/login/ HTTP/1.1" 200 4165
backend-1   | [26/Jan/2026 13:34:12] "GET /admin/login/ HTTP/1.1" 200 4165

[sahilds1]

@TineoC To help us review this PR, can you please file a GitHub Issue describing the local dev issues and fill out the PR template in your PR: https://github.com/CodeForPhilly/balancer-main/blob/develop/pull_request_template.md?plain=1