generated from bisco/codex-bootstrap
feat: bootstrap HoopScout scouting app
This commit is contained in:
bisco
@@ -0,0 +1,48 @@
|
||||
# ADR-0001: Bootstrap Stack and Data Boundaries
|
||||
|
||||
Date: 2026-06-03
|
||||
|
||||
Status: Accepted
|
||||
|
||||
## Context
|
||||
|
||||
HoopScout needs a private MVP for scouting male basketball players, initially focused on European leagues and a single season. The requested stack is Docker, Django, PostgreSQL, and Angular. Development must follow pragmatic TDD and keep implementation choices simple.
|
||||
|
||||
External sources such as RealGM and Proballers may be useful, but the project does not yet have authorized API credentials, provider terms review, or a data license.
|
||||
|
||||
## Decision
|
||||
|
||||
Use Docker Compose with:
|
||||
|
||||
- Django REST Framework for the backend API and Django admin;
|
||||
- PostgreSQL for persistent relational data;
|
||||
- Angular for the scouting dashboard;
|
||||
- synthetic demo data through a Django management command;
|
||||
- authenticated API access through Django session/basic authentication;
|
||||
- user profile roles modeled as `admin`, `scout`, and `viewer`.
|
||||
|
||||
Do not add automated scraping or copied external datasets in the MVP. Keep provider metadata fields so future authorized imports can preserve source references.
|
||||
|
||||
## Consequences
|
||||
|
||||
The MVP can be run locally and tested inside containers with a small, understandable architecture. The schema supports player identity, position, optional role, league, team, season averages, totals, advanced statistics, and best/worst game summaries.
|
||||
|
||||
Real data ingestion remains a later feature and must be designed around provider authorization and licensing.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- Scrape RealGM or Proballers immediately: rejected because provider authorization and terms are not yet documented.
|
||||
- Add JWT authentication immediately: deferred because Django session/basic authentication is enough for local restricted use.
|
||||
- Add notes, exports, and watchlists immediately: deferred because they are outside the initial MVP scope.
|
||||
|
||||
## Security impact
|
||||
|
||||
All API endpoints require authentication. Secrets are read from environment variables and `.env` is ignored by Git. Containers use non-root users where practical. PostgreSQL is not exposed outside the Compose network.
|
||||
|
||||
## Operational impact
|
||||
|
||||
The application is local-only. Production deployment, TLS, backup automation, stricter role permissions, and source ingestion jobs require later ADRs.
|
||||
|
||||
## Rollback
|
||||
|
||||
Revert the bootstrap commit and remove local Docker volumes if database state can be discarded.
|
||||
+26
-9
@@ -1,13 +1,30 @@
|
||||
# Architecture
|
||||
|
||||
Describe the project architecture here.
|
||||
HoopScout is a private scouting application composed of three local Docker services:
|
||||
|
||||
Include:
|
||||
- `frontend`: Angular single-page application for player search and profile review.
|
||||
- `backend`: Django REST Framework API with Django admin for restricted data management.
|
||||
- `db`: PostgreSQL database for users, leagues, teams, players, season stats, and game logs.
|
||||
|
||||
- main components;
|
||||
- runtime dependencies;
|
||||
- data flow;
|
||||
- persistence;
|
||||
- external integrations;
|
||||
- deployment topology;
|
||||
- relevant ADRs.
|
||||
## Data Flow
|
||||
|
||||
Users authenticate through Django session/basic authentication. The Angular application calls `/api/players/` with search and filter query parameters. The backend returns paginated player summaries ranked by efficiency and points, plus detailed player profiles at `/api/players/{id}/`.
|
||||
|
||||
## Persistence
|
||||
|
||||
The initial schema stores:
|
||||
|
||||
- users and user profiles with `admin`, `scout`, and `viewer` roles;
|
||||
- male player identity, bio, position, optional role, measurements in cm/kg, nationality, current team, and external source metadata;
|
||||
- leagues and teams, with an initial focus on European leagues;
|
||||
- one active season;
|
||||
- per-season averages, totals, and advanced metrics;
|
||||
- per-game logs for best and worst performance views.
|
||||
|
||||
## External Integrations
|
||||
|
||||
No automated external ingestion is included in the MVP. Demo data is synthetic. RealGM, Proballers, or similar data providers require a later authorized API/import decision before real data is collected.
|
||||
|
||||
## Relevant ADRs
|
||||
|
||||
- `docs/adr/0001-bootstrap-stack-and-data-boundaries.md`
|
||||
|
||||
+30
-11
@@ -1,15 +1,34 @@
|
||||
# Deployment
|
||||
|
||||
Describe how this project is deployed.
|
||||
The MVP supports local Docker Compose deployment only.
|
||||
|
||||
Include:
|
||||
## Local Environment
|
||||
|
||||
- environments;
|
||||
- Docker/Compose usage;
|
||||
- required configuration;
|
||||
- secrets handling;
|
||||
- exposed ports;
|
||||
- volumes;
|
||||
- networks;
|
||||
- deployment commands;
|
||||
- rollback procedure.
|
||||
```bash
|
||||
cp .env.example .env
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
Initialize the database:
|
||||
|
||||
```bash
|
||||
docker compose run --rm backend python manage.py migrate
|
||||
docker compose run --rm backend python manage.py seed_demo_data
|
||||
docker compose run --rm backend python manage.py createsuperuser
|
||||
```
|
||||
|
||||
## Exposed Ports
|
||||
|
||||
- `8000`: Django API and admin.
|
||||
- `4200`: Angular development server.
|
||||
|
||||
PostgreSQL is not published to the host.
|
||||
|
||||
## Volumes
|
||||
|
||||
- `postgres_data`: PostgreSQL data.
|
||||
- `frontend_node_modules`: frontend dependencies inside Docker.
|
||||
|
||||
## Rollback
|
||||
|
||||
For code rollback, revert the relevant Git commit and rebuild the Compose services. For local data rollback, restore a database backup or remove the `postgres_data` volume if disposable demo data is acceptable.
|
||||
|
||||
+34
-9
@@ -1,13 +1,38 @@
|
||||
# Operations
|
||||
|
||||
Describe operational procedures.
|
||||
## Startup
|
||||
|
||||
Include:
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
- startup and shutdown;
|
||||
- health checks;
|
||||
- logs;
|
||||
- monitoring;
|
||||
- backup and restore;
|
||||
- routine maintenance;
|
||||
- known operational risks.
|
||||
## Shutdown
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
The PostgreSQL container has a `pg_isready` healthcheck. Backend and frontend smoke checks are manual in the MVP:
|
||||
|
||||
- backend: open `http://localhost:8000/admin/`;
|
||||
- frontend: open `http://localhost:4200/`.
|
||||
|
||||
## Logs
|
||||
|
||||
```bash
|
||||
docker compose logs backend
|
||||
docker compose logs frontend
|
||||
docker compose logs db
|
||||
```
|
||||
|
||||
## Backup and Restore
|
||||
|
||||
No automated backup is configured for the MVP. Use `pg_dump` from the database container before preserving real scouting data.
|
||||
|
||||
## Known Operational Risks
|
||||
|
||||
- The frontend uses the Angular development server and is not production hardened.
|
||||
- Role-specific permissions are modeled but not yet enforced per action.
|
||||
- External data ingestion is intentionally not automated yet.
|
||||
|
||||
+22
-6
@@ -1,19 +1,35 @@
|
||||
# Runbook
|
||||
|
||||
Operational runbook for this project.
|
||||
|
||||
## Common tasks
|
||||
|
||||
Document routine operational tasks here.
|
||||
Apply migrations:
|
||||
|
||||
```bash
|
||||
docker compose run --rm backend python manage.py migrate
|
||||
```
|
||||
|
||||
Seed demo data:
|
||||
|
||||
```bash
|
||||
docker compose run --rm backend python manage.py seed_demo_data
|
||||
```
|
||||
|
||||
Create an admin user:
|
||||
|
||||
```bash
|
||||
docker compose run --rm backend python manage.py createsuperuser
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Document known issues, symptoms, checks, and remediation steps.
|
||||
- If the frontend shows an authentication error, sign in through `http://localhost:8000/admin/` or DRF login first.
|
||||
- If backend startup fails, check database readiness with `docker compose logs db`.
|
||||
- If dependencies change, rebuild with `docker compose build --no-cache backend frontend`.
|
||||
|
||||
## Rollback
|
||||
|
||||
Document rollback procedures here.
|
||||
Revert the Git commit containing the change and rebuild containers. If local database state must also be reverted, restore a database dump or recreate the `postgres_data` volume for disposable data.
|
||||
|
||||
## Emergency contacts
|
||||
|
||||
Document project-specific escalation paths if appropriate.
|
||||
Not configured for the local MVP.
|
||||
|
||||
+30
-12
@@ -1,16 +1,34 @@
|
||||
# Security
|
||||
|
||||
Describe security assumptions and controls.
|
||||
HoopScout is initially intended for local or restricted-network use by a small private group.
|
||||
|
||||
Include:
|
||||
## Authentication and Authorization
|
||||
|
||||
- authentication;
|
||||
- authorization;
|
||||
- network exposure;
|
||||
- TLS/certificates;
|
||||
- secrets management;
|
||||
- logging of sensitive data;
|
||||
- container privileges;
|
||||
- filesystem permissions;
|
||||
- dependency management;
|
||||
- relevant ADRs.
|
||||
- API endpoints require an authenticated Django user.
|
||||
- Django admin is enabled for controlled data management.
|
||||
- Users have a profile role: `admin`, `scout`, or `viewer`.
|
||||
- Role-specific authorization is not enforced beyond authentication in the MVP.
|
||||
|
||||
## Network Exposure
|
||||
|
||||
Local Compose exposes:
|
||||
|
||||
- backend on `8000`;
|
||||
- frontend on `4200`;
|
||||
- PostgreSQL only inside the Compose network.
|
||||
|
||||
## Secrets
|
||||
|
||||
`.env.example` contains placeholders only. Real local values must be stored in `.env`, which is ignored by Git.
|
||||
|
||||
## Containers
|
||||
|
||||
Backend and frontend containers run as non-root users. PostgreSQL uses the official image defaults and a named volume.
|
||||
|
||||
## Data Sources
|
||||
|
||||
The repository does not include credentials, scraping logic, or copied external datasets. RealGM, Proballers, and other provider data must be integrated only through authorized APIs or a documented compliant import process.
|
||||
|
||||
## Known Dependency Findings
|
||||
|
||||
`npm audit` reports moderate vulnerabilities through `webpack-dev-server -> sockjs -> uuid` in the Angular development toolchain, with no available fix at the time of implementation. The dev server is intended for local restricted use only and must not be exposed publicly.
|
||||
|
||||
+12
-12
@@ -1,23 +1,23 @@
|
||||
# Testing
|
||||
|
||||
Describe how tests are executed.
|
||||
All tests must run inside Docker containers.
|
||||
|
||||
All tests should run inside Docker containers.
|
||||
## Canonical Test Command
|
||||
|
||||
## Canonical test command
|
||||
Run these commands from the repository root:
|
||||
|
||||
```bash
|
||||
CHANGE_ME
|
||||
docker compose run --rm backend ruff check .
|
||||
docker compose run --rm backend pytest
|
||||
docker compose run --rm frontend npm test
|
||||
docker compose config
|
||||
```
|
||||
|
||||
## Test categories
|
||||
|
||||
Describe applicable categories:
|
||||
- Backend API tests use `pytest` and `pytest-django`.
|
||||
- Backend linting uses `ruff`.
|
||||
- Frontend unit tests use `vitest`.
|
||||
- Docker Compose validation uses `docker compose config`.
|
||||
|
||||
- unit tests;
|
||||
- integration tests;
|
||||
- linting;
|
||||
- formatting checks;
|
||||
- Ansible syntax checks;
|
||||
- Docker/Compose validation;
|
||||
- smoke tests.
|
||||
The initial TDD coverage verifies authentication requirements, player filtering, default ranking, profile performance summaries, user roles, and frontend filter serialization.
|
||||
|
||||
Reference in New Issue
Block a user