# angelykcoder/eggsimulator architecture

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

- Interactive diagram: https://gitdiagram.com/angelykcoder/eggsimulator
- Repository: https://github.com/angelykcoder/eggsimulator

## Overview

GallinaCoin simulates poultry farms, egg-market conditions, token trading, and farmer reinvestment over monthly periods. The visible browser workflow is user → role-specific dashboard → local simulation API → persisted state → refreshed client/farmer views. The sampled browser API explicitly uses localStorage, while the repository also contains a FastAPI service layer with parallel domain operations and JSON-file state; the excerpts do not establish that the browser currently calls that backend. Backend wiring is shown from its routes and service calls; unsampled README and business-rule details are not inferred.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser application"]
  node_page["Dashboard page"]
  node_app["App controller"]
  node_clientview["Client dashboard"]
  node_farmerview["Farmer dashboard"]
  node_clientapi["Browser simulator"]
end

subgraph group_backend["Backend API"]
  node_routes["API routes"]
end

subgraph group_domain["Simulation domain"]
  node_market["Market pricing"]
  node_farms["Farm operations"]
  node_trading["Token trading"]
  node_simulation["Monthly simulation"]
end

subgraph group_persistence["State and study data"]
  node_marketdata["Browser market study"]
  node_localstate[("Browser state")]
  node_statemgr["State manager"]
  node_diskstate[("Backend state")]
  node_studyfile["Market study"]
end

node_user(("User"))
node_apiuser(("API caller"))

node_user -->|"uses"| node_page
node_page -->|"presents"| node_app
node_app -->|"loads state"| node_clientapi
node_clientapi -->|"reads/writes"| node_localstate
node_clientapi -->|"reads study"| node_marketdata
node_app -->|"renders client"| node_clientview
node_app -->|"renders farmer"| node_farmerview
node_clientview -->|"trades tokens"| node_clientapi
node_farmerview -->|"manages farms"| node_clientapi
node_apiuser -->|"calls endpoints"| node_routes
node_routes -->|"reads state"| node_statemgr
node_routes -->|"advances month"| node_simulation
node_routes -->|"buys/sells"| node_trading
node_routes -->|"farm actions"| node_farms
node_statemgr -->|"reads/writes"| node_diskstate
node_statemgr -->|"seeds initial state"| node_studyfile
node_market -->|"loads study"| node_studyfile
node_simulation -->|"loads/saves state"| node_statemgr
node_simulation -->|"prices eggs"| node_market
node_simulation -->|"calculates farm results"| node_farms
node_trading -->|"loads/saves state"| node_statemgr
node_trading -->|"looks up farm"| node_farms
node_farms -->|"loads/saves state"| node_statemgr

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_page,node_app,node_clientview,node_farmerview,node_clientapi,node_user toneBlue
class node_routes toneAmber
class node_market,node_farms,node_trading,node_simulation,node_apiuser toneMint
class node_marketdata,node_localstate,node_statemgr,node_diskstate,node_studyfile toneRose
```

## Components

### Browser application

- **Dashboard page**
- **App controller**
- **Client dashboard**
- **Farmer dashboard**
- **Browser simulator**

### Backend API

- **API routes**

### Simulation domain

- **Market pricing**
- **Farm operations**
- **Token trading**
- **Monthly simulation**

### State and study data

- **Browser market study**
- **Browser state**
- **State manager**
- **Backend state**
- **Market study**

### Other components

- **User**
- **API caller**

## Connections

- User → Dashboard page: uses
- Dashboard page → App controller: presents
- App controller → Browser simulator: loads state
- Browser simulator → Browser state: reads/writes
- Browser simulator → Browser market study: reads study
- App controller → Client dashboard: renders client
- App controller → Farmer dashboard: renders farmer
- Client dashboard → Browser simulator: trades tokens
- Farmer dashboard → Browser simulator: manages farms
- API caller → API routes: calls endpoints
- API routes → State manager: reads state
- API routes → Monthly simulation: advances month
- API routes → Token trading: buys/sells
- API routes → Farm operations: farm actions
- State manager → Backend state: reads/writes
- State manager → Market study: seeds initial state
- Market pricing → Market study: loads study
- Monthly simulation → State manager: loads/saves state
- Monthly simulation → Market pricing: prices eggs
- Monthly simulation → Farm operations: calculates farm results
- Token trading → State manager: loads/saves state
- Token trading → Farm operations: looks up farm
- Farm operations → State manager: loads/saves state