Project PULSE

PULSE is a modern, modular, highly available management system built for multi-sport youth clubs (with an initial focus on soccer). It handles age-pool administration, ephemeral roster/team building, à-la-carte sub-registration for events, and dynamic field/tournament logistics.

---

🏗️ Architecture & Tech Stack

The project follows Clean Architecture (Ports & Adapters) principles as a modular monolithic Go backend, ensuring strict separation of business domains and enabling a future migration to microservices without heavy refactoring (see ADR-003).

Backend

• Language: Go 1.26
• HTTP router: Chi Router (RESTful API)
• Database: PostgreSQL 16+ with strict schema isolation (core, tournament, scheduling, finance, evaluation) — no cross-schema joins allowed (see ADR-003)
• DB driver: pgx/v5 via pgxpool
• Migrations: golang-migrate (run automatically on startup)
• API docs: OpenAPI 3.1 generated by Huma, served at /docs
• Observability: OpenTelemetry OTLP/gRPC (otelchi) (see ADR-006)
• Security: passwords hashed with bcrypt, client IP resolved via middleware.ClientIPFromHeader (not the deprecated, CVE-affected RealIP)
• Container: multi-stage build, final image on distroless/static-debian12:nonroot

Frontend

• Framework: React 19 + Vite (TypeScript)
• Styling & UI: Tailwind CSS v4, Radix UI, clsx + tailwind-merge (Light/Dark theme, WCAG 2.1 AA accessibility)
• Icons: Lucide React
• Testing: Vitest + React Testing Library + Happy-DOM + vitest-axe
• Web observability: OpenTelemetry Web SDK (@opentelemetry/sdk-trace-web)

Infrastructure & Tooling

• Containerization: Docker Compose (postgres, redis, backend, frontend) — see docker-compose.yml
• Dev environment: Devcontainer (GitHub Codespaces / VS Code), see .devcontainer/
• CI/CD: GitHub Actions — lint, unit tests + coverage, security scanning (Snyk), quality analysis (SonarQube Cloud), image build & publish to GHCR
• Code quality: pre-commit (golangci-lint, ESLint, Prettier, markdownlint, sqlfluff, cross-schema-join guard)

---

📁 Project Structure

pulse/
├── cmd/
│   └── backend/                   # Go server entry point
├── internal/
│   └── core/
│       ├── adapters/
│       │   ├── http/               # HTTP handlers (chi)
│       │   └── postgres/           # Repository implementations
│       └── ports/                  # Domain contracts (interfaces, DTOs)
├── migrations/                     # SQL scripts, per schema
├── pkg/
│   ├── database/                   # PGX connection & migration runner
│   └── observability/              # OpenTelemetry pipeline
├── frontend/                       # Vite + React + TypeScript app
├── deployments/
│   └── docker/                     # Backend & frontend Dockerfiles
├── docs/
│   ├── explanation/                # Understanding-oriented
│   ├── how-to/                     # Task-oriented
│   ├── refs/                       # → REFERENCE MATERIAL (user-owned, AI never modifies)
│   │   ├── adr/                    # Architecture Decision Records
│   │   └── templates/              # Doc templates
│   │   └── Architecture.md         # Architecture
│   ├── tutorials/                  # Learning-oriented
│   └── ROADMAP_TODO.md             # Project progress tracking
├── docker-compose.yml
└── .devcontainer/                  # Codespaces / VS Code config

---

🚀 Quick Start

Option A — Docker Compose (recommended)

cp .env.example .env   # create it if it doesn't exist yet, see the variables below
docker compose up -d

The backend listens on http://localhost:8080 (see API_PORT), the frontend on http://localhost:3000 (see FRONTEND_PORT).

Option B — Local development without containers

Prerequisites

• Go 1.26+
• Node.js 24+ & npm
• PostgreSQL 16+ and Redis (local, or via docker compose up -d postgres redis)

Backend

export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=postgres
export DB_PASSWORD=postgres_secret
export DB_NAME=pulse_db
export DB_SSLMODE=disable
export PORT=8080

go mod download
go run ./cmd/backend

Frontend

cd frontend
npm ci
npm run dev

Option C — Codespaces / Devcontainer

Open the repo in GitHub Codespaces, or via "Reopen in Container" in VS Code. The environment (Go, Node, sqlc, air, golang-migrate, postgresql-client) is provisioned automatically, and Postgres/Redis start via docker compose.

---

🧪 Tests & Quality

# Backend
go test -v -race -coverprofile=coverage-go.out ./internal/... ./pkg/...

# Frontend
cd frontend && npm run test -- --coverage

# Pre-commit (full lint before every commit)
pre-commit install
pre-commit run --all-files

---

📚 Documentation

• docs/adr/ — Architecture Decision Records (justified technical decisions)
• docs/ARCHITECTURE.md — architecture overview
• docs/SCHEMA.md — database schema
• docs/ROADMAP_TODO.md — progress tracking
• /swagger/index.html (with the backend running) — interactive API documentation

---

🤝 Contributing

See CONTRIBUTING.md. Any external contribution requires accepting the CLA.md (see ADR-005).

🔐 Security

See SECURITY.md to report a vulnerability.

📄 License

This project is distributed under the Business Source License 1.1, non-commercial (see ADR-005). Self-hosting is free for non-profit clubs and associations; reselling or operating it as a commercial SaaS is prohibited without a separate commercial license. Full details: ADR-005 and LICENSE.