The Search is an open-source, self-hostable surf intelligence PWA that combines marine and weather forecasts, local spot knowledge, and surfer preferences to produce explainable, personalized surf recommendations.
The project is in its foundation phase. A production-shaped vertical slice now proves the installable PWA, same-origin ownership-safe profile and favorite APIs, hardened containers, forward-only PostGIS migrations, user-data isolation, and pull-request quality gates. Forecast ingestion and recommendation behavior are the next milestones.
The Search should answer a practical question:
Given this surf spot, this surfer, and this time window, is it worth going?
It will turn forecast data into recommendations that are:
- personal to the surfer's experience and preferences;
- specific to a surf spot rather than only a geographic coordinate;
- explainable and reproducible;
- honest about uncertainty and data quality;
- useful on mobile, including degraded connectivity scenarios.
- React and TypeScript progressive web application
- Go modular-monolith backend
- PostgreSQL with PostGIS
- Deterministic recommendation engine
- AI used for explanation, not as the decision authority
- OCI containers
- Kubernetes target runtime
- GitHub Actions for continuous integration
- Argo CD for GitOps continuous delivery
The decisions and their trade-offs are recorded in docs/adr.
- Safety information is never reduced to a single quality score.
- Forecasts, transformations, and recommendations retain provenance.
- Recommendations are reproducible from versioned inputs and rules.
- Private surf spots and user data are private by default.
- The application remains useful without an LLM.
- Operational complexity must solve a concrete problem or a stated learning objective.
api/openapi/ Versioned HTTP contract
backend/ Go API and production container
database/ PostgreSQL role bootstrap and database initialization
frontend/ React and TypeScript PWA and production container
docs/
adr/ Architectural decision records
architecture/ System boundaries and technical direction
operations/ Development, CI/CD, and runtime guidance
product/ Vision, scope, and domain language
security/ Threat model and security guidance
.github/ Repository governance and automation
scripts/ Repeatable operational checks
Install the pinned Go and Node.js versions, then run the local quality contract:
npm ci --prefix frontend
make verify
make database-testTo exercise the production containers and the PWA-to-API proxy:
make compose-smokeFor an interactive local stack, run make compose-up and open http://127.0.0.1:8081. The stack waits for PostgreSQL and applies pending migrations before starting the API. Stop it with make compose-down. See database operations before resetting data or changing migrations.
Every change starts from an issue, preserves the documented boundaries, and passes the same verification locally and in CI. See CONTRIBUTING.md, the development workflow, the CI/CD contract, and SECURITY.md.
Licensed under the Apache License 2.0. See LICENSE.