HelixNet

An auth-driven FastAPI platform hosting La Piazza, a peer-to-peer rental marketplace, plus a POS system, a self-hosted music player, and internal QA/backlog tooling.

Author: Angel Kenel. Collaborator: Tigs (Claude). Made in Sicily.

All services run as Docker containers, orchestrated by docker compose.

• Caddy for the reverse proxy (was Traefik; switched for simpler Let's Encrypt + path routing on Hetzner)
• Keycloak for OIDC, RS256 JWTs verified by FastAPI
• SQLAlchemy 2.x async + asyncpg
• Pydantic v2 for everything
• Alpine.js + Tailwind CDN on templates (no SPA — server-rendered first, JS for interactivity)
• Puppeteer for PDF generation (postcards, SOPs)
• Playwright for E2E tests (scaffolded under tests/)

Locked naming convention across all apps:

Hetzner host: single CX32 box (4 vCPU, 8 GB RAM, ~7 €/mo). Caddy fronts everything via path-based routing.

Deploy SOP (mandatory — scripts/smoke-test.sh is the gate):

git push # local
ssh root@HETZNER_IP "cd /opt/helixnet && git pull && \
 cd hetzner && docker compose -f docker-compose.uat.yml \
 up -d --build helix-platform"
ssh root@HETZNER_IP "cd /opt/helixnet && bash scripts/smoke-test.sh hetzner"

Never deploy to prod without explicit staging sign-off. No exceptions, even for "low-risk" changes.

• Docker + Docker Compose
• mkcert for local HTTPS (or accept self-signed warnings)
• 8 GB free RAM, ~20 GB disk

git clone <repo-url> helixnet
cd helixnet
cp .env.example .env # then edit secrets
make up # full stack build + start
make status # check all containers healthy

Add to /etc/hosts:

127.0.0.1 helix.local
127.0.0.1 keycloak.helix.local
127.0.0.1 lapiazza.helix.local

Browse to https://helix.local/ and you should land on the La Piazza homepage.

All test users across all realms use password helix_pass. Examples:

Full persona list: scripts/seed-staging-personas.sh.

Five roles, JWT-enforced at every endpoint.

API endpoints (all under /api/v1/pos/): products (GET/POST/PUT/DELETE), transactions (POST), checkout (POST), reports/daily-summary (GET).

Realm config: helix-pos-realm-dev.json, auto-imported on startup.

Implemented and live:

• Listings — create, edit, search (with pg_trgm similarity), publish/unpublish, raffle conversion
• Calendar — per-listing availability with blackout dates (recurring weekdays + date ranges)
• Quotation requests — buyer → seller flow, integrated into messages inbox
• Raffles — entries, draws, cancel/refund
• Helpboard — AI-assisted ticket drafting, escalation
• Messages inbox — threaded, with quotation requests surfaced inline
• Backlog feedback — public submission with session-report + screenshot capture
• QA dashboard — bug + test tracker (same auth as backlog)

Tested personas (scripts/seed-staging-personas.sh): Alice (buyer), Bob (seller), Carol (admin), Eve, Gia, Gemma, plus 11 imported demo users. All use helix_pass.

"No ads. No algorithm. No monthly ransom. Just music."

Self-hosted Swing Music instance with a curated library organized by timezone — songs follow the sunrise around the planet.

PACIFIC DAWN AUSTRALIA JAPAN-KOREA SOUTHEAST ASIA
INDIA-PAKISTAN MIDDLE EAST AFRICA EAST AFRICA WEST
EUROPE EAST EUROPE WEST AMERICAS EAST AMERICAS WEST
 |
 SOUL FOUNDATION

Each track ships with synced lyrics (.lrc), a MANIFEST.md for provenance, and a WISDOM.md of between-song quotes. Tracks pulled via yt-dlp and curated by hand.

cd compose/helix-media
docker compose -f media-stack.yml up -d
# Visit http://localhost:1970

Library: compose/helix-media/music/sunrise-chain/

helixnet/
 BorrowHood/ La Piazza application (FastAPI + templates)
 src/ Models, routers, services, templates
 tests/ Pytest suite
 compose/
 helix-media/ Music player stack
 keycloak/ Realm JSON + bootstrap
 debllm/ Self-healing monitor (dormant)
 docs/
 business/ Postcards, SOPs, business plans
 design/ Architecture design docs (LP CLI drafts, etc.)
 runbooks/ Operator runbooks (secret rotation, etc.)
 testing/ QA + UAT documentation
 hetzner/ Production compose + env files (.env gitignored)
 scripts/
 smoke-test.sh 25-check post-deploy gate
 preflight.sh 28-point environment inspector
 rotate-secrets.sh Interactive secret rotation
 seed-staging-personas.sh Persona seeding
 sop-to-pdf.js Puppeteer-driven PDF generation
 src/ HelixNet kernel: FastAPI app, Keycloak,
 POS, Camper, Backlog routes
 stories/ The Great Escape narrative
 tests/ Playwright E2E suite
 UFA_r2p/ Print-ready PDFs (postcards, labels)
 videos/ Video production assets (MP4s gitignored)
 CLAUDE.md Persistent context for the AI co-pilot
 Makefile `make up`, `make status`, `make logs`

The FastAPI app validates JWTs with Keycloak's RS256 public key.

1. Open https://helix.local/docs
2. Click Authorize, choose OAuth2 password flow
3. Enter:

   username: helix_user
   password: helix_pass
   client_id: helix_client
   

4. Submit, then any /api/v1/users/me call should return 200.

TOKEN=$(curl -sk -X POST \
 "https://keycloak.helix.local/realms/helix/protocol/openid-connect/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "client_id=helix_client" \
 -d "username=helix_user" \
 -d "password=helix_pass" \
 -d "grant_type=password" | jq -r '.access_token')
curl -sk "https://helix.local/api/v1/users/me" \
 -H "Authorization: Bearer $TOKEN"

This is not a beginner project. Expect to troubleshoot certificate trust (mkcert), CORS, container networking, Caddy path routing, Keycloak realm configuration, Postgres ownership transfers, and the occasional 3am DB password drift. Proceed only if you have grit, coffee, and curiosity.

• Wire CI staging-green gate into prod deploys
• Build Order-to-Cash, Procure-to-Pay, and mixed-role Playwright scenario suites
• Rename Hetzner UAT compose files to PROD
• Complete secret rotation (in flight)
• BorrowHood → La Piazza rebrand sweep (artifacts only; live app is already La Piazza)
• Demo path: /demo route with guided auto-login for first-time visitors
• Decide DebLLM revival vs. archive

Full task list lives in the repo's internal task tracker.

TBD — for now: "All rights reserved. If you fork it, tell Angel why."

"Be water, my friend." — Bruce Lee "Casa è dove parcheggi." — Home is where you park it.