website/README.md

# Platform Architecture & Tech Stack

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.