pulse-score/
├── cmd/api/              # Application entry point
│   └── main.go
├── internal/             # Private application code
│   ├── config/           # Configuration management
│   ├── handler/          # HTTP handlers
│   ├── middleware/        # HTTP middleware
│   ├── model/            # Domain models
│   ├── repository/       # Database access layer
│   └── service/          # Business logic
├── pkg/                  # Reusable packages
├── migrations/           # Database migrations
├── scripts/
│   └── init-db/          # PostgreSQL initialization scripts
├── web/                  # React/TypeScript frontend (Vite + TailwindCSS v4)
│   └── src/
│       └── components/
├── docker-compose.dev.yml
├── Makefile
└── .env.example

Tech Stack

Backend: Go (net/http)
Frontend: React 19, TypeScript, Vite, TailwindCSS v4
Database: PostgreSQL 16
Deployment: Docker, Nginx, VPS

Prerequisites

Go 1.24+
Node.js 20+
Docker & Docker Compose

Getting Started

1. Clone and configure

cp .env.example .env

2. Start the database

docker compose -f docker-compose.dev.yml up -d

3. Run the API

make run

The API starts on http://localhost:8080. Health check: GET /healthz

4. Run the frontend

cd web
pnpm install
pnpm run dev

The frontend starts on http://localhost:5173.

Shipping to Production (VPS)

PulseScore ships to production through a manual GitHub Actions workflow:

Workflow: .github/workflows/deploy-prod.yml
Trigger: Actions → Deploy Production → Run workflow
Inputs:
- ref (branch/tag/SHA to deploy)
- run_migrations (reserved; currently no-op)

Required GitHub repository secrets

VPS_HOST — production server hostname/IP
VPS_USER — SSH user on the VPS
VPS_SSH_KEY — private SSH key for deploy user
VPS_APP_DIR — absolute path to repo on VPS (example: /opt/pulse-score)

Optional:

VPS_PORT — SSH port (defaults to 22 if omitted by your SSH client/server config)

What deployment does

The deploy workflow SSHes into your VPS and:

Checks out the requested ref
Ensures the external Docker network web exists
Pulls latest DB image and rebuilds API/Web images with --pull
Runs docker compose -f docker-compose.prod.yml up -d --remove-orphans
Verifies DB readiness (pg_isready) and API health (/healthz)

Manual deploy fallback (on VPS)

If needed, you can run the same deploy logic directly on the server:

./scripts/deploy/vps-deploy.sh

Development Commands

Backend (Makefile)

Command	Description
`make build`	Build the Go binary
`make run`	Build and run the API
`make test`	Run tests with race detection
`make lint`	Run `go vet`
`make dev-db`	Start development PostgreSQL
`make dev-db-down`	Stop development PostgreSQL
`make migrate-up`	Run database migrations up
`make migrate-down`	Roll back database migrations

Frontend (web/)

Command	Description
`pnpm run dev`	Start Vite dev server
`pnpm run seo:validate`	Validate SEO catalog integrity (families/slugs/keywords)
`pnpm run seo:artifacts`	Generate sitemap artifacts in `web/public/sitemaps/`
`pnpm run seo:prerender`	Pre-render SEO routes into `web/dist/`
`pnpm run build`	Production build + SEO validate/artifacts/prerender
`pnpm run lint`	ESLint check
`pnpm run format`	Format with Prettier
`pnpm run preview`	Preview production build

Billing & Subscription (Epic 12)

PulseScore now includes a dedicated Stripe billing domain (separate from Stripe customer-data integration):

Plan catalog: free, growth, scale (internal/billing/plans.go)
Protected billing APIs:
- GET /api/v1/billing/subscription
- POST /api/v1/billing/checkout (admin)
- POST /api/v1/billing/portal-session (admin)
- POST /api/v1/billing/cancel (admin)
Public billing webhook:
- POST /api/v1/webhooks/stripe-billing

Required production billing env vars

STRIPE_BILLING_SECRET_KEY
STRIPE_BILLING_PUBLISHABLE_KEY
STRIPE_BILLING_WEBHOOK_SECRET
STRIPE_BILLING_PRICE_GROWTH_MONTHLY
STRIPE_BILLING_PRICE_GROWTH_ANNUAL
STRIPE_BILLING_PRICE_SCALE_MONTHLY
STRIPE_BILLING_PRICE_SCALE_ANNUAL

Optional:

STRIPE_BILLING_PORTAL_RETURN_URL (defaults to http://localhost:5173/settings/billing)

License

Licensed under GPL-3.0-or-later. See LICENSE.