Internal developer documentation for the SynLotto platform infrastructure, covering the core platform modules where comments were updated and maintained. This serves as the reference for how the runtime environment is constructed and how foundational systems interact.

Current as of: Oct 29, 2025

Platform Initialization Overview

At startup the platform initializes and wires the systems required for HTTP request routing, security, session management, and database persistence.

Boot sequence executed from bootstrap:

Config Load

→ MySQL Connect + Validate → EnsureInitialSchema (Embedded SQL, idempotent) → Register gob types for session data → Initialize SessionManager (SCS) → Create Gin Router (Logging, static assets) → Inject *App into Gin context for handler access → Route Handler → SCS LoadAndSave wrapping → CSRF Wrapping (NoSurf) → http.Server construction (graceful shutdown capable)

Application boot from main.go:

Initialize template helpers

→ Attach global middleware (Auth → Remember) → Register route groups (Home, Account, Admin, Syndicate, Statistics) → Start serving HTTP requests → Graceful shutdown on SIGINT/SIGTERM

Platform Files & Responsibilities

internal/platform/bootstrap/loader.go

The application kernel constructor.

Creates and wires:

Config (loaded externally)
MySQL DB connection (with pooling + UTF8MB4 + UTC)
Idempotent initial schema application
SCS SessionManager
Gin router with logging
Static mount: /static → ./web/static
App → Gin context injection (c.Set("app", app))
Custom NoRoute/NoMethod/Recovery error pages
Final HTTP handler wrapping: Gin → SCS → CSRF

Orchestrates: stability of middleware order, security primitives, and transport-level behavior.

cmd/api/main.go

Top-level runtime control.

Initializes template helpers (session manager + site meta)
Applies Auth and Remember middleware
Registers route groups
Starts server in goroutine
Uses timed graceful shutdown

No business logic or boot infrastructure allowed here.

internal/platform/config/types.go

Strongly typed runtime settings including:

Config Sections:

Database (server, pool settings, credentials)
HTTP server settings
Session lifetimes + cookie names
CSRF cookie name
External API licensing
Site metadata

Durations are strings — validated and parsed in platform/session.

internal/platform/config/load.go

Loads JSON configuration into Config struct.

Pure function
No mutation of global state
Errors propagate to bootstrap

internal/platform/config/config.go

Singleton wrapper for global configuration access.

Init ensures config is assigned only once
Get allows consumers to retrieve config object

Used sparingly — dependency injection via App is primary recommended path.

internal/platform/session/session.go

Creates and configures SCS session manager.

Configured behaviors:

Absolute lifetime (default 12h if invalid config)
Idle timeout enforcement
Cookie security:
- HttpOnly = true
- SameSite = Lax
- Secure = based on productionMode

Responsible only for platform session settings — not auth behavior or token rotation.

internal/platform/csrf/csrf.go

Applies NoSurf global CSRF protection.

Cookie name from config
HttpOnly always
Secure cookie in production
SameSite = Lax
Wraps after SCS to access stored session data

Requires template integration for token distribution.

internal/platform/database/schema.go

Ensures base DB schema exists using embedded SQL.

Behavior:

Probes users table
If any rows exist → assume schema complete
Otherwise → executes InitialSchema in a single TX

Future: schema versioning required for incremental changes.

Tech Stack Summary

Concern	Technology
Web Framework	Gin
Session Manager	SCS (server-side)
CSRF Protection	NoSurf
Database	MySQL
Migrations	Embedded SQL applied on startup
Templates	Go html/template
Static Files	Served via Gin from web/static
Authentication	Cookie-based session auth
Error Views	Custom 404, 405, Recovery
Config Source	JSON configuration file
Routing	Grouped per feature under internal/http/routes

Security Behavior Summary

Protection	Current Status
CSRF enforced globally	Yes
Session cookies HttpOnly	Yes
Secure cookie in production	Yes
SameSite policy	Lax
Idle timeout enforcement	Enabled
Session rotation on login	Enabled
DB foreign keys	Enabled
Secrets managed via JSON config	Temporary measure

Security improvements tracked separately.

Architectural Rules

Layer	May Access	Must Not Access
Platform	DB, Session, Config	Handlers, routes
Handlers	App, DB, SessionManager, helpers	Bootstrap
Template helpers	Pure logic only	DB, HTTP
Middleware	Session, App, routing	Template rendering
Error pages	No DB or session dependency	Bootstrap internals

These boundaries are currently enforced in code.

Known Technical Debt

Duration parsing and validation improvements
Environment variable support for secret fields
CSRF token auto-injection in templates
Versioned DB migrations
Replace remaining global config reads
Add structured logging for platform initialization
Expanded session store options (persistent)

Documented in developer backlog for scheduling.