skyrama_tui/CLAUDE.md

Skyrama TUI

A terminal user interface for a Skyrama-clone airport management game, built with BubbleTea.

Tech Stack

• Go 1.22
• github.com/charmbracelet/bubbletea — TUI framework
• github.com/charmbracelet/lipgloss — terminal styling
• github.com/charmbracelet/bubbles — list, textinput, etc.
• github.com/go-sql-driver/mysql — MySQL driver
• golang.org/x/crypto/bcrypt — password hashing
• sqlc — SQL → Go codegen (generated files in internal/db/)

Project Structure

cmd/skyrama/main.go          # Entry point: rootModel (login → app screen transition)
internal/
  db/
    client.go                # Thin wrapper over sqlc Queries; auth, transactions, row mappers
    db.go / querier.go /
    queries.sql.go / models.go  # sqlc-generated files (do not edit by hand)
  model/model.go             # Domain types: Airport, Plane, PlayerPlane, Building, Contract, …
  style/style.go             # All lipgloss styles and colors
  ui/
    app.go                   # AppModel: tab bar, 10s tick, window sizing
    login.go                 # Login / register screen
    airport_view.go          # Tab 0: resources, XP bar
    fleet.go                 # Tab 1: planes, launch/land flights
    buildings.go             # Tab 2: owned buildings + build catalogue
    contracts.go             # Tab 3: active delivery contracts
    shop.go                  # Tab 4: buy planes
sql/
  schema.sql                 # MySQL DDL (source of truth)
  queries.sql                # sqlc input queries
sqlc.yaml                    # sqlc configuration
buidl.bat                    # build script (go build -o skyrama ./cmd/skyrama/)

Database

• Engine: MySQL
• Default DSN: skyramaUser:Skyrama1234.@tcp(127.0.0.1:3306)/skyrama_clone?parseTime=true
• Override via --dsn flag or SKYRAMA_DSN environment variable.
• Schema must be applied before first run: sql/schema.sql

Build & Run

# Build
buidl.bat
# or
go build -o skyrama.exe ./cmd/skyrama/

# Run (uses default DSN if SKYRAMA_DSN not set)
.\skyrama.exe

# Run with custom DSN
.\skyrama.exe --dsn "user:pass@tcp(host:port)/dbname?parseTime=true"

# Regenerate sqlc files after editing sql/queries.sql
sqlc_generate.bat

Architecture

Screen flow

rootModel (main.go) owns two screens:

1. screenLogin → ui.LoginModel — handles LoginSuccessMsg / LoginErrMsg
2. screenApp → ui.AppModel — full game TUI after login

On LoginSuccessMsg, rootModel builds AppModel and injects all sub-models (Fleet, Buildings, Contracts, Shop) with the resolved airportID.

AppModel (ui/app.go)

• Owns all tab sub-models as value/pointer fields.
• Routes tea.Msg to the active tab sub-model.
• Fires a 10-second tick that:
  1. Calls RefreshResources (regenerates fuel/passengers via MySQL TIMESTAMPDIFF)
  2. Auto-lands planes ready to land (GetPlanesReadyToLand + LandFlight)

db.Client (internal/db/client.go)

Wraps the sqlc *Queries object. All multi-step DB operations are wrapped in transactions:

• BuyPlane — deducts cash, inserts player_planes, logs transaction
• LaunchFlight — deducts fuel, sets plane status to flying, logs transaction
• LandFlight — awards cash + XP, parks plane in hangar, logs transaction
• ConstructBuilding — deducts cash, inserts airport_buildings, logs transaction

Some queries use raw database/sql (e.g. GetAirportBuildings, GetActiveContracts) because the sqlc-generated join queries are not yet wired up.

Domain model (internal/model/model.go)

Key types: Airport, Plane, PlayerPlane, Building, AirportBuilding, Contract, Country, User.

PlayerPlane.TimeRemainingSeconds() computes seconds until landing client-side.
Contract.ProgressPct() returns delivery progress as an integer percentage.

Tab index constants: TabAirport=0, TabFleet=1, TabBuildings=2, TabContracts=3, TabShop=4.

Key Bindings

Key	Action
1-5 / tab / shift+tab	Switch tabs
↑↓ / j k	Navigate lists
enter / space	Select / action
/	Filter list
r	Refresh current tab
h / l	Switch sub-tabs (Buildings)
q / ctrl+c	Quit

Fleet tab: enter on idle plane → launch; enter on flying plane → check/land if ready.
Buildings tab: h/l or ←→ → toggle Owned ↔ Build catalogue; enter in catalogue → construct.
Shop tab: enter / b → buy selected plane (deducts cash, parks in first hangar).

DB Schema Overview

Core tables: users, airports, planes, player_planes, buildings, airport_buildings, countries, products, airport_contracts, airport_inventory.
Log tables: currency_transaction_logs, completed_flight_routes_log.
Stage 1 (not yet active): recipes, building_products.

Plane statuses: idle | maintenance | boarding | taxiing | flying
Building types: none | storage | support | operation | passive | shop | production
Aircraft sizes: small | medium | large | huge
Aircraft types: plane | helicopter | seaplane | spaceship

Development Stages

• Stage 0 (current): Launch planes to country's base airport, basic resources, buildings, shop.
• Stage 1: NPCs, cargo planes, shop buildings, recipes, inventory.
• Stage 2: Player progression, building upgrades, effects, complex recipes.
• Stage 3: TBD.