HSFC
System Architecture

Hullbridge Holland Tour

Team management, live match control, real-time chat & tournament tracking โ€” Built by TheGroots Technology

18
Web Pages
18
Mobile Screens
50+
API Routes
18+
DB Tables
3
WebSockets
3
Platforms
~16K
Lines of Code
๐ŸŒ Live App ๐Ÿ“– Docs
Architecture Overview
๐Ÿ–ฅ๏ธ

Frontend โ€” Next.js 16

React 19 + Tailwind v4
Home
/
  • Feature cards (login-gated)
  • Welcome message + role title
  • Dutch flag gradients
Fixtures
/fixtures
  • Table view with RSVP
  • Match/Training/Social tabs
  • Attendance modal
  • Admin: create/edit/delete
Accommodation
/accommodation
  • 9 chalets with guest allocations
  • Eurocamp De Schatberg
Team Chat
/chat
  • 3 channels (team/players/staff)
  • Real-time WebSocket
  • Typing indicators
  • Image attachments
  • Unread badges
  • Reply & forward messages
  • Emoji reactions (WhatsApp-style)
Lineups
/lineups
  • Pitch diagram (5+ formations)
  • Drag & drop positioning
  • SVG shirt icons with numbers
  • Custom formation creator
Live Match
/livematch
  • Real-time score updates
  • WebSocket timeline
Feed
/feed
  • Posts, comments, reactions
  • Auto match reports
Stats
/stats
  • W/D/L, goals, cards
  • Player profiles
Gallery
/gallery
  • Photo upload to Storage Box
  • Lightbox viewer
Tour Summary
/season
  • Season overview
  • Top scorers, results
Manager Panel
/manage
  • 10 admin sections
  • Fixtures, lineup, live control
  • Squad, parents, coaches
  • Game reports + PDF export
Settings
/settings
  • Notification preferences
  • Password change
โ†“
โšก

Backend โ€” FastAPI (Python)

Async + WebSocket
Auth
/api/auth/*
  • JWT (HS256, 24h expiry)
  • bcrypt passwords
  • Forced password change
  • Rate limited (10/min)
Teams
/api/teams/*
  • CRUD, invites, join
  • Member management
  • Parent-player links
Events
/api/events/*
  • Fixtures CRUD
  • Recurring events (weekly)
  • RSVP system
  • Auto RSVP reminders (2 days)
  • Attendance grid
Match
/api/match/*
  • Live event recording
  • Auto score tracking
  • Match report generation
Chat
/api/chat/*
  • Messages + attachments
  • Read receipts
  • Unread counts
Notifications
/api/notifications/*
  • In-app + WebSocket push
  • Email via Resend
  • User preferences
โ†“
๐Ÿ—„๏ธ

PostgreSQL + Hetzner Storage Box

15 Tables + 1TB SFTP
users
idUUID PK
emailunique
password_hashbcrypt
must_change_passwordbool
teams
idUUID PK
namestring
age_groupstring
team_members
roleadmin/staff/player/parent
titlee.g. "The Gaffer"
statuspending/approved
shirt_numberint
events
typematch/training/social
match_typefriendly/league/tournament
statusscheduled/live/completed
home_score / away_scoreint
match_events
typegoal/card/sub/kickoff/...
minuteint
detailJSONB
chat_messages
channelteam/players/staff
server_seqbigint (ordered)
attachment_urlstring
notifications
typersvp/match_event/...
is_readbool
photos
urlstorage box path
captionstring
Real-Time WebSocket Channels
๐Ÿ’ฌ Chat
/ws/chat/{team}/{channel}
  • JWT authenticated
  • Messages broadcast
  • Typing indicators
  • Delete broadcasts
โšฝ Match
/ws/match/{event_id}
  • JWT authenticated
  • Goals, cards, subs
  • Score updates
  • Status changes
๐Ÿ”” Notifications
/ws/notifications/{user_id}
  • JWT authenticated + user verified
  • Real-time bell push
  • RSVP, match events
  • New fixtures
Notification Architecture

Every significant action triggers notifications through multiple channels:

TriggerIn-App BellWebSocket PushEmail (Resend)Feed Post
New Fixture Createdโœ… All membersโœ… Real-timeโ€”โœ… Auto announcement
RSVP Changeโœ… Adminsโœ… Real-timeโœ… Admin emailsโ€”
Goal Scoredโœ… All membersโœ… Real-timeโ€”โ€”
Card Issuedโœ… All membersโœ… Real-timeโ€”โ€”
Full Timeโœ… All membersโœ… Real-timeโ€”โœ… Match report
Infrastructure & Security
Hetzner VPS
204.168.157.10
  • Ubuntu 24.04
  • nginx reverse proxy
  • Let's Encrypt SSL
  • PM2 process manager
Hetzner Storage Box
u567309.your-storagebox.de · 1TB SFTP
  • Photo storage
  • Chat attachments
  • SSH key auth
Vercel DNS
hullbridgeontour.com
  • A record โ†’ VPS
  • Domain purchased
Resend
Email delivery
Security
๐Ÿ” Authentication
  • JWT with HS256 (64-byte secret)
  • bcrypt password hashing
  • 24-hour token expiry
  • Min 8-char passwords
  • QR Login & Magic Links
  • WebSocket JWT auth
๐Ÿ›ก๏ธ Firewall (UFW)
  • SSH (22), HTTP (80), HTTPS (443)
  • All other ports blocked
  • PostgreSQL not exposed
๐Ÿšซ fail2ban
  • SSH brute force protection
  • 3 max retries, 1hr ban
  • systemd journal backend
๐Ÿ”‘ SSH
  • Key-only authentication
  • Password auth disabled
  • Root login: prohibit-password
โšก Rate Limiting
  • Global: 120 req/min
  • Login: 10/min
  • Register: 5/min
  • 429 Too Many Requests
๐Ÿ”’ Security Headers
  • HSTS (1 year)
  • X-Frame-Options: DENY
  • X-Content-Type-Options: nosniff
  • CORS: restricted origins
  • Referrer-Policy: strict
Tech Stack
Frontend
  • Next.js 16 (standalone)
  • React 19
  • Tailwind CSS v4
  • Lucide React icons
Backend
  • FastAPI (Python 3.12)
  • SQLAlchemy (async)
  • asyncpg driver
  • Pydantic v2
Database
  • PostgreSQL 16
  • 15 tables
  • UUID primary keys
  • JSONB for flexible data
Real-Time
  • FastAPI WebSocket
  • 3 WS endpoints
  • Ping/pong keepalive
Deployment
  • PM2 process manager
  • nginx reverse proxy
  • rsync-based deploys
  • Let's Encrypt auto-renew
Android App
  • React Native 0.84
  • Bottom tab navigation
  • Dark/Light mode
  • QR code login
  • 18 screens
  • APK distributed
iOS App
  • React Native 0.84 (shared codebase)
  • iPad + iPhone support
  • TestFlight distribution
  • HSFC badge app icon
  • Landscape & portrait