phase 0.3

README.md

@@ -0,0 +1,89 @@
+# Skyrama TUI
+
+A terminal user interface for Skyrama Clone built with [BubbleTea](https://github.com/charmbracelet/bubbletea).
+
+## Structure
+
+```
+skyrama-tui/
+├── cmd/
+│   └── skyrama/
+│       └── main.go          # Entry point, login → app wiring
+├── internal/
+│   ├── db/
+│   │   └── client.go        # MySQL client wrapping all queries
+│   ├── model/
+│   │   └── model.go         # Domain types (Airport, Plane, Building, …)
+│   ├── style/
+│   │   └── style.go         # All lipgloss styles, colors, resource bars
+│   └── ui/
+│       ├── app.go            # Root AppModel: tab bar, tick, window sizing
+│       ├── airport_view.go   # Airport overview panel (resources, XP bar)
+│       ├── buildings.go      # Buildings tab: owned list + build catalogue
+│       ├── contracts.go      # Contracts tab: active delivery contracts
+│       ├── fleet.go          # Fleet tab: planes, launch / land flights
+│       ├── login.go          # Login / register screen
+│       └── shop.go           # Shop tab: buy planes from catalogue
+└── go.mod
+```
+
+## Setup
+
+```bash
+# 1. Clone / copy into your project
+git clone <your-repo>
+cd skyrama-tui
+
+# 2. Install dependencies
+go mod tidy
+
+# 3. Run (DB must already have the schema applied)
+SKYRAMA_DSN='skyramaUser:Skyrama1234.@tcp(127.0.0.1:3306)/skyrama_clone?parseTime=true' go run ./cmd/skyrama/
+
+# Or compile and run:
+go build -o skyrama ./cmd/skyrama/
+./skyrama --dsn 'user:pass@tcp(host:port)/dbname?parseTime=true'
+```
+
+## Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `1-5` / `tab` / `shift+tab` | Switch tabs |
+| `↑↓` / `j k` | Navigate lists |
+| `enter` / `space` | Select / action |
+| `/` | Filter current list |
+| `r` | Refresh current tab |
+| `h / l` | Switch sub-tabs (Buildings) |
+| `q` / `ctrl+c` | Quit |
+
+### Fleet tab
+| Key | Action |
+|-----|--------|
+| `enter` on idle plane | Launch flight (deducts fuel, finds runway) |
+| `enter` on flying plane | Check & land if travel time elapsed |
+
+### Buildings tab
+| Key | Action |
+|-----|--------|
+| `h / l` or `→ ←` | Toggle Owned ↔ Build catalogue |
+| `enter` in Build catalogue | Construct building (deducts cash) |
+
+### Shop tab
+| Key | Action |
+|-----|--------|
+| `enter` / `b` | Buy selected plane (deducts cash, parks in first hangar) |
+
+## Auto-refresh
+
+Every **10 seconds** the TUI:
+1. Runs `UPDATE airports SET current_fuel = ..., current_passengers = ...` to regenerate resources.
+2. Checks for planes ready to land (`flying` status + elapsed travel time) and processes landings automatically.
+
+## Architecture Notes
+
+- **No sqlc dependency at runtime** — `internal/db/client.go` talks raw `database/sql` for full
+  control and to avoid a second build step. Swap it for your sqlc `Queries` type any time.
+- All DB mutations are wrapped in transactions (buy plane, build, launch, land).
+- BubbleTea message types are defined in each file that owns them (`FleetLoadedMsg`, `ShopErrMsg`, …).
+- The `AppModel` owns all sub-models as value fields and forwards `tea.Msg` to the active one.