infra/stacks/f1-stream/files/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-02-17

Directory Layout

f1-stream/
├── main.go                 # Entry point, service initialization, signal handling
├── go.mod                  # Go module definition
├── go.sum                  # Dependency lock file
├── Dockerfile              # Container image definition
├── redeploy.sh            # Kubernetes redeployment script
├── index.html             # HTML template served at root
├── internal/              # Private Go packages
│   ├── auth/              # WebAuthn authentication and session management
│   ├── models/            # Domain data types
│   ├── server/            # HTTP handlers, routes, middleware
│   ├── store/             # File-based persistence layer
│   ├── scraper/           # Reddit content scraper
│   └── proxy/             # HTTP proxy with rate limiting
├── static/                # Frontend assets served to clients
│   ├── index.html         # Main SPA template
│   ├── css/               # Stylesheets
│   └── js/                # Client-side JavaScript modules
└── .planning/             # Planning/documentation directory
    └── codebase/          # Architecture analysis documents

Directory Purposes

Root Level:

• Purpose: Service configuration and entry point
• Contains: Go module, main executable, Docker configuration, shell scripts
• Key files: main.go (service bootstrap), go.mod (dependencies)

internal/:

• Purpose: Private packages (not importable by external code)
• Contains: All business logic, separated by concern
• Key pattern: Each subdirectory is a distinct Go package with clear responsibility

internal/auth/:

• Purpose: User authentication, session management, context helpers
• Contains: WebAuthn ceremony handlers, session token management, user-in-context utilities
• Key files:
  • auth.go: Registration/login handlers, ceremony session storage, credential validation
  • context.go: Request context helpers for passing user data between middleware and handlers

internal/models/:

• Purpose: Domain model definitions
• Contains: User, Stream, ScrapedLink, Session type definitions
• Key files: models.go (all types, includes WebAuthn interface implementations)

internal/server/:

• Purpose: HTTP API and routing layer
• Contains: Handler functions, route registration, middleware implementations
• Key files:
  • server.go: Server struct, route registration, API handlers (streams, admin, public endpoints)
  • middleware.go: LoggingMiddleware, RecoveryMiddleware, AuthMiddleware, RequireAuth, RequireAdmin, OriginCheck

internal/store/:

• Purpose: Persistent storage abstraction over file system
• Contains: JSON file operations, per-entity storage methods, atomic write patterns
• Key files:
  • store.go: Store struct, directory initialization, JSON helper functions (readJSON, writeJSON)
  • streams.go: Stream CRUD operations, publish toggle, seeding
  • users.go: User lookup, credential updates, admin count
  • sessions.go: Session creation, validation, expiry cleanup
  • scraped.go: Scraped link persistence, active link filtering

internal/scraper/:

• Purpose: Background content aggregation
• Contains: Interval-based scraper, Reddit-specific scraper logic
• Key files:
  • scraper.go: Scraper service, interval-based run loop, manual trigger mechanism, deduplication logic
  • reddit.go: Reddit API polling, F1 keyword filtering, URL extraction (not included in sample reads but referenced)

internal/proxy/:

• Purpose: HTTP content fetching with security controls and rate limiting
• Contains: Rate limiter, private IP validation, response modification
• Key files: proxy.go (implements http.Handler, rate limiting, content fetching, base tag injection)

static/:

• Purpose: Frontend assets served to browser
• Contains: HTML template and client-side code
• Key files:
  • index.html: SPA HTML template (includes script tags loading js/)
  • js/app.js: Toast notifications, dialog system, tab switching, initialization
  • js/auth.js: Registration/login UI, WebAuthn client ceremony
  • js/streams.js: Stream display, filtering, admin operations
  • js/utils.js: Shared utilities (HTML escaping)
  • css/: Stylesheets for app UI

Key File Locations

Entry Points:

• main.go: Service initialization, dependency injection, signal handling, goroutine startup

Configuration:

• Environment variables read in main.go (LISTEN_ADDR, DATA_DIR, SCRAPE_INTERVAL, etc.)
• WebAuthn config passed to auth.New()
• .env files not tracked (see .gitignore)

Core Logic:

• Request routing: internal/server/server.go:registerRoutes()
• Auth logic: internal/auth/auth.go
• Data storage: internal/store/store.go and per-entity files
• Scraping: internal/scraper/scraper.go
• Proxying: internal/proxy/proxy.go

Testing:

• No test files present in codebase (see TESTING.md concerns section)

Naming Conventions

Files:

• Go source files: lowercase with underscores (e.g., auth.go, middleware.go)
• JavaScript files: lowercase with hyphens or underscores (e.g., app.js, auth.js)
• JSON data files: lowercase (e.g., streams.json, users.json, sessions.json)

Directories:

• Go packages: lowercase, single word preferred (e.g., auth, store, models)
• Frontend assets: plural nouns (e.g., static, css, js)

Functions:

• Go: CamelCase (exported), camelCase (unexported)
• JavaScript: camelCase throughout (e.g., loadPublicStreams(), showToast())

Types:

• Go structs: CamelCase (e.g., User, Stream, Store, Auth)
• Methods: CamelCase (e.g., BeginLogin(), AddStream())

Variables:

• Go: camelCase (e.g., listenAddr, dataDir, adminUsername)
• JavaScript: camelCase (e.g., container, userID, sessionToken)

Where to Add New Code

New Feature (e.g., new stream filter):

• Primary code: Add handler in internal/server/server.go, register route in registerRoutes()
• Store operations: Add method to appropriate file in internal/store/ (likely streams.go)
• Frontend: Add UI in static/ and API call in static/js/streams.js or new module
• Models: Extend types in internal/models/models.go if new fields needed

New Authentication Method:

• Core implementation: New file in internal/auth/ (e.g., oauth.go)
• Handlers: Add methods following WebAuthn pattern (BeginXxx, FinishXxx)
• Routes: Register in registerRoutes()
• Frontend: Add form/button in static/js/auth.js

New Background Service (e.g., content validator):

• Implementation: New file in internal/ or new package internal/validator/
• Integration: Initialize in main() alongside scraper.New()
• Lifecycle: Use context pattern from scraper's Run(ctx) method
• Storage: Use existing Store instance

Utilities/Helpers:

• Shared by Go packages: Add to package where most useful, or create new internal/util/ package
• Shared by frontend: Add to static/js/utils.js or create new module
• Shared helpers pattern: Functions not tied to single package, used across multiple

Special Directories

internal/:

• Purpose: Enforce package privacy (cannot be imported by external code)
• Generated: No
• Committed: Yes

static/:

• Purpose: Served directly to clients via http.FileServer
• Generated: No (hand-written frontend)
• Committed: Yes

.planning/codebase/:

• Purpose: Architecture documentation for development guidance
• Generated: No (manually created by mapping process)
• Committed: Yes

Data Directory (runtime):

• Purpose: Persistent JSON files (streams.json, users.json, sessions.json, scraped.json)
• Location: Specified by DATA_DIR env var (default /data)
• Generated: Yes (created on first run)
• Committed: No (varies per deployment environment)

Import Patterns

Go Package Imports:

• Standard library first: import ("context" "fmt" "log")
• Internal packages second: import ("f1-stream/internal/auth" "f1-stream/internal/store")
• External third-party last: import ("github.com/go-webauthn/webauthn/webauthn")

Cross-Package Dependencies:

• Server depends on: Auth, Store, Proxy, Scraper, Models
• Auth depends on: Store, Models
• Scraper depends on: Store, Models
• Proxy depends on: none (standalone service)
• Store depends on: Models
• Models depends on: external WebAuthn library only

---

Structure analysis: 2026-02-17