# oceanosdev/spacetraders-ui architecture

> Architecture diagram of the GitHub repository oceanosdev/spacetraders-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oceanosdev/spacetraders-ui
- Repository: https://github.com/oceanosdev/spacetraders-ui

## Overview

SpaceTraders Fleet Console is an authenticated dashboard for viewing an agent and operating its fleet, markets, and contracts. The principal flow is token entry, agent loading, then navigating to domain consoles for ship management, trading, or contract delivery tracking. The sampled code confirms authentication, agent and waypoint requests, and market-waypoint selection; feature API details and page wiring are not sampled, so those connections are left out.

Main entry points: [`src/App.tsx`](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/App.tsx) (App dashboard), [`src/features/navigation/components/AppContent.tsx`](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/navigation/components/AppContent.tsx) (Console navigation), [`src/features/ships/ShipsPage.tsx`](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/ShipsPage.tsx) (Ship console), [`src/features/contracts/ContractsPage.tsx`](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/ContractsPage.tsx) (Contracts console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and shell"]
  node_app["App dashboard<br/>[App.tsx]"]
  node_authgate["Auth gate<br/>[AuthGate.tsx]"]
  node_tokenform["Token entry<br/>[TokenForm.tsx]"]
  node_authstate["Token state<br/>[authSlice.ts]"]
  node_navigation["Console navigation<br/>[AppContent.tsx]"]
  node_api["API client<br/>[spacetradersApi.ts]"]
end

subgraph group_fleet["Fleet operations"]
  node_ships["Ship console<br/>[ShipsPage.tsx]"]
  node_shipapi["Ship operations API<br/>[shipsApi.ts]"]
  node_shipactions["Ship actions"]
  node_shipnav["Ship navigation"]
end

subgraph group_markets["Market operations"]
  node_markets["Markets console<br/>[MarketsPage.tsx]"]
  node_marketapi["Market operations API<br/>[marketsApi.ts]"]
  node_marketstate["Market selection"]
  node_waypointlookup["Market waypoints"]
  node_systemwaypoints["Waypoint lookup"]
end

subgraph group_contracts["Contract operations"]
  node_contracts["Contracts console<br/>[ContractsPage.tsx]"]
  node_contractapi["Contract operations API<br/>[contractsApi.ts]"]
  node_delivery["Delivery tracking"]
  node_countdown["Deadline countdown<br/>[countdown.ts]"]
end

node_user(("Console user"))
node_spacetraders{{"SpaceTraders API"}}

node_user -->|"opens console"| node_app
node_app -->|"checks access"| node_authgate
node_authgate -->|"reads token"| node_authstate
node_authgate -->|"requests token"| node_tokenform
node_tokenform -->|"sets token"| node_authstate
node_app -->|"loads agent"| node_api
node_api -->|"reads token"| node_authstate
node_api -->|"requests data"| node_spacetraders
node_app -->|"shows consoles"| node_navigation
node_navigation -->|"opens console"| node_ships
node_navigation -->|"opens console"| node_markets
node_navigation -->|"opens console"| node_contracts
node_waypointlookup -->|"filters waypoints"| node_systemwaypoints
node_systemwaypoints -->|"fetches pages"| node_api
node_markets -->|"selects market"| node_marketstate
node_marketstate -.->|"uses market actions"| node_marketapi
node_ships -.->|"uses ship actions"| node_shipapi
node_ships -->|"offers operations"| node_shipactions
node_ships -->|"offers navigation"| node_shipnav
node_contracts -.->|"uses contract actions"| node_contractapi
node_contracts -->|"tracks progress"| node_delivery
node_contracts -->|"shows deadlines"| node_countdown

click node_app "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/App.tsx"
click node_authgate "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/components/AuthGate.tsx"
click node_tokenform "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/components/TokenForm.tsx"
click node_authstate "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/authSlice.ts"
click node_navigation "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/navigation/components/AppContent.tsx"
click node_api "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/services/spacetradersApi.ts"
click node_ships "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/ShipsPage.tsx"
click node_shipapi "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/api/shipsApi.ts"
click node_shipactions "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/components/ship-actions/ShipActionsPanel.tsx"
click node_shipnav "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/components/ship-navigation/ShipNavigationPanel.tsx"
click node_markets "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/MarketsPage.tsx"
click node_marketapi "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/api/marketsApi.ts"
click node_marketstate "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/hooks/useMarketsPageState.ts"
click node_waypointlookup "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/hooks/useSystemMarketWaypoints.ts"
click node_systemwaypoints "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/systems/hooks/useSystemWaypoints.ts"
click node_contracts "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/ContractsPage.tsx"
click node_contractapi "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/api/contractsApi.ts"
click node_delivery "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/model/contractDelivery.ts"
click node_countdown "https://github.com/oceanosdev/spacetraders-ui/blob/master/src/utils/countdown.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_authgate,node_tokenform,node_authstate,node_navigation,node_api,node_user toneBlue
class node_ships,node_shipapi,node_shipactions,node_shipnav toneAmber
class node_markets,node_marketapi,node_marketstate,node_waypointlookup,node_systemwaypoints,node_spacetraders toneMint
class node_contracts,node_contractapi,node_delivery,node_countdown toneRose
```

## Components

### Access and shell

- [App dashboard](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/App.tsx): `src/App.tsx`
- [Auth gate](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/components/AuthGate.tsx): `src/features/auth/components/AuthGate.tsx`
- [Token entry](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/components/TokenForm.tsx): `src/features/auth/components/TokenForm.tsx`
- [Token state](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/auth/authSlice.ts): `src/features/auth/authSlice.ts`
- [Console navigation](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/navigation/components/AppContent.tsx): `src/features/navigation/components/AppContent.tsx`
- [API client](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/services/spacetradersApi.ts): `src/services/spacetradersApi.ts`

### Fleet operations

- [Ship console](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/ShipsPage.tsx): `src/features/ships/ShipsPage.tsx`
- [Ship operations API](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/api/shipsApi.ts): `src/features/ships/api/shipsApi.ts`
- [Ship actions](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/components/ship-actions/ShipActionsPanel.tsx): `src/features/ships/components/ship-actions/ShipActionsPanel.tsx`
- [Ship navigation](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/ships/components/ship-navigation/ShipNavigationPanel.tsx): `src/features/ships/components/ship-navigation/ShipNavigationPanel.tsx`

### Market operations

- [Markets console](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/MarketsPage.tsx): `src/features/markets/MarketsPage.tsx`
- [Market operations API](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/api/marketsApi.ts): `src/features/markets/api/marketsApi.ts`
- [Market selection](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/hooks/useMarketsPageState.ts): `src/features/markets/hooks/useMarketsPageState.ts`
- [Market waypoints](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/markets/hooks/useSystemMarketWaypoints.ts): `src/features/markets/hooks/useSystemMarketWaypoints.ts`
- [Waypoint lookup](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/systems/hooks/useSystemWaypoints.ts): `src/features/systems/hooks/useSystemWaypoints.ts`

### Contract operations

- [Contracts console](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/ContractsPage.tsx): `src/features/contracts/ContractsPage.tsx`
- [Contract operations API](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/api/contractsApi.ts): `src/features/contracts/api/contractsApi.ts`
- [Delivery tracking](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/features/contracts/model/contractDelivery.ts): `src/features/contracts/model/contractDelivery.ts`
- [Deadline countdown](https://github.com/oceanosdev/spacetraders-ui/blob/master/src/utils/countdown.ts): `src/utils/countdown.ts`

### Other components

- **Console user**
- **SpaceTraders API**

## Connections

- Console user → App dashboard: opens console
- App dashboard → Auth gate: checks access
- Auth gate → Token state: reads token
- Auth gate → Token entry: requests token
- Token entry → Token state: sets token
- App dashboard → API client: loads agent
- API client → Token state: reads token
- API client → SpaceTraders API: requests data
- App dashboard → Console navigation: shows consoles
- Console navigation → Ship console: opens console
- Console navigation → Markets console: opens console
- Console navigation → Contracts console: opens console
- Market waypoints → Waypoint lookup: filters waypoints
- Waypoint lookup → API client: fetches pages
- Markets console → Market selection: selects market
- Market selection → Market operations API: uses market actions
- Ship console → Ship operations API: uses ship actions
- Ship console → Ship actions: offers operations
- Ship console → Ship navigation: offers navigation
- Contracts console → Contract operations API: uses contract actions
- Contracts console → Delivery tracking: tracks progress
- Contracts console → Deadline countdown: shows deadlines