How vichally20/ouroborous works
1. Overall shape
- This is a cross-platform Flutter app with a game-like structure, not a traditional client/server app.
- The core logic lives in lib/; the android/, ios/, web/, macos/, windows/, and linux/ folders are platform runners and packaging layers.
2. App entry and shell
- lib/main.dart is the entrypoint into the Flutter app.
- The app likely starts into a hub/intro flow and then routes into gameplay, inventory, navigation, and other screens through the state layer.
3. Presentation layer
- lib/ui/screens/ contains the main user-facing screens: intro, game_hub, you_hub, chronicle, combat, inventory, navigation, persona, stats, talents, and settings.
- lib/ui/widgets/ provides reusable UI primitives such as etched_container and manuscript_controls.
- lib/core/theme/ and lib/core/constants/ define the visual system (manuscript_theme, colors, typography), which suggests a consistent stylized UI across screens.
4. Game runtime layer
- lib/game/ is the real-time gameplay subsystem.
- city_game.dart appears to be the main game runtime container.
- components/ includes runtime entities like player, enemy, projectile, and infinite_background_art, plus hud_overlay for game UI layered over the playfield.
- This layer is responsible for moment-to-moment play and likely drives combat and exploration visuals separately from the standard Flutter screen stack.
5. Story and content engine
- lib/game/story_engine.dart is the narrative orchestration layer.
- It consumes bundled content from assets/story/ and assets/data/, including chapter JSON, bestiary, encounters, weapons lore, and ancient lore.
- This indicates a content-driven architecture: story progression and world data are externalized into assets rather than hardcoded in UI.
6. Domain model layer
- lib/models/ holds the shared game schema: character, combat, story, inventory, skills, loadouts, vitals, talents, perks, and attributes.
- These models form the boundary between narrative/game logic and presentation.
- The same model types are reused by state managers, the story engine, and the gameplay runtime, which keeps screens thin and data-driven.
7. State and coordination layer
- lib/states/ contains the application controllers: game_controller, combat_state, inventory_state, navigation_state, player_state, and settings_state.
- This is the orchestration boundary that coordinates screen transitions, player progression, combat state, and preferences.
- The naming suggests a centralized app state approach where UI and runtime components read from and react to these state objects.
8. Feature partitioning
- lib/sandbox/ is a separate experimental or isolated gameplay area with its own sandbox_launcher, sandbox_dungeon_screen, and sandbox_dungeon_controller.
- This looks like a self-contained testbed for dungeon mechanics or combat systems, separate from the main progression loop.
- In an architecture diagram, it should be shown as a secondary feature area branching off the main app flow.
9. Primary data flow
- Bundled JSON assets feed the story engine and model layer.
- The state layer transforms those domain objects into app state.
- Screens render that state and dispatch user actions back into controllers.
- The game runtime uses the same underlying models but presents them through a real-time interactive layer, with HUD overlays and gameplay components.
10. Platform boundaries
- The native folders are standard Flutter host projects, not feature logic.
- Android/iOS/macOS/Windows/Linux/Web exist to launch the same Dart application with platform-specific bootstrapping, icons, manifests, and build settings.
- There is no evidence of a backend, database, or remote API; the architecture is primarily local, asset-backed, and client-only.
11. Supporting docs and tests
- docs/PRD.md and features.md provide product/feature context.
- test/widget_test.dart and the platform test targets are minimal, suggesting the project is still early-stage or scaffolded.
12. How to draw it
- A good diagram would show: platform shell → app entry → state/controllers → screens/game runtime → shared models → bundled assets.
- The sandbox should be drawn as a parallel feature branch.
- Theme/constants sit beside the UI layer, while story/data assets feed both the story engine and gameplay systems.
Main entry points: game_controller.dart Game ctrl · city_game.dart City game · game_hub_screen.dart Game hub · story_engine.dart Story engine
Components 34
Platform runners
Flutter host projects and packaging layers for each target platform.
App core
Entry point, shared theme, state, and domain models.
- Main · Starts the Flutter app and hands off to the app shell.
lib/main.dart - Theme · Shared visual styling and manuscript theme.
lib/core/theme/manuscript_theme.dart - Colors · Core color constants used by the visual system.
lib/core/constants/colors.dart - Typography · Shared text styling constants.
lib/core/constants/typography.dart - Game ctrl · Coordinates high-level app flow and game progression.
lib/states/game_controller.dart - Combat state · Tracks combat flow and outcomes.
lib/states/combat_state.dart - Inventory · Manages inventory and item-related state.
lib/states/inventory_state.dart - Navigation · Coordinates map and movement-related state.
lib/states/navigation_state.dart - Player state · Holds player progression and character state.
lib/states/player_state.dart - Settings · Stores user preferences and app settings.
lib/states/settings_state.dart - Models · Shared game data types reused across UI, state, and runtime.
lib/models/story_models.dart
Presentation
User-facing screens and reusable widgets.
- Intro · Entry and onboarding flow.
lib/ui/screens/intro_screen.dart - Game hub · Primary hub for progression and mode selection.
lib/ui/screens/game_hub_screen.dart - You hub · Character-centric hub and profile area.
lib/ui/screens/you_hub_screen.dart - Combat · Turn or encounter-facing combat presentation.
lib/ui/screens/combat_screen.dart - Inventory · Inventory browsing and item management UI.
lib/ui/screens/inventory_screen.dart - Navigation · Route and location selection UI.
lib/ui/screens/navigation_screen.dart
Game runtime
Real-time gameplay loop and runtime entities.
- HUD · In-game heads-up UI layered over gameplay.
lib/game/ui/hud_overlay.dart - City game · Main real-time game container and loop.
lib/game/city_game.dart - Player · Runtime player entity.
lib/game/components/player.dart - Enemy · Runtime hostile entity.
lib/game/components/enemy.dart - Projectile · Runtime attack or effect entity.
lib/game/components/projectile.dart - Background · Scrollable or infinite background art layer.
lib/game/components/infinite_background_art.dart
Content
Bundled narrative and world data assets.
- Story engine · Loads and advances narrative content from assets.
lib/game/story_engine.dart - Chapter 1 · Bundled chapter content.
assets/story/chapter_1.json - Chapter 2 · Bundled chapter content.
assets/story/chapter_2.json - Bestiary · Creature and enemy reference data.
assets/data/bestiary.json - Encounters · Encounter tables and scenario data.
assets/data/encounters.json
Sandbox
Isolated experimental gameplay branch.
- Sandbox launch · Entry point for the isolated sandbox feature.
lib/sandbox/sandbox_launcher.dart - Sandbox dungeon · Sandbox dungeon play screen.
lib/sandbox/sandbox_dungeon_screen.dart - Sandbox ctrl · Controller for sandbox dungeon flow.
lib/sandbox/sandbox_dungeon_controller.dart
Connections 44
- Main → Game ctrl: boots · App entry initializes the main app controller.
- Game ctrl → Intro: routes to · High-level state drives the first user-facing flow.
- Game ctrl → Game hub: routes to · Main hub is the central navigation destination.
- Game ctrl → Combat state: owns · Coordinates combat-related application state.
- Game ctrl → Inventory: owns · Coordinates inventory-related application state.
- Game ctrl → Navigation: owns · Coordinates map and movement state.
- Game ctrl → Player state: owns · Coordinates player progression state.
- Game ctrl → Settings: owns · Coordinates preference state.
- Game ctrl → Story engine: uses · App flow consumes narrative progression.
- Intro → Game hub: advances to · Intro flow leads into the hub.
- Game hub → You hub: opens · Hub branches into character-centric views.
- Game hub → Combat: opens · Hub can enter combat presentation.
- Game hub → Inventory: opens · Hub can enter inventory management.
- Game hub → Navigation: opens · Hub can enter navigation flow.
- Combat → Combat state: reads · Combat UI reflects combat controller state.
- Inventory → Inventory: reads · Inventory UI reflects inventory controller state.
- Navigation → Navigation: reads · Navigation UI reflects navigation controller state.
- You hub → Player state: reads · Character hub reflects player progression.
- Combat state → Models: uses · Combat logic relies on shared domain types.
- Inventory → Models: uses · Inventory logic relies on shared domain types.
- Navigation → Models: uses · Navigation logic relies on shared domain types.
- Player state → Models: uses · Player progression is modeled with shared schema.
- Story engine → Chapter 1: loads · Narrative engine consumes chapter assets.
- Story engine → Chapter 2: loads · Narrative engine consumes chapter assets.
- Story engine → Bestiary: loads · Story and encounter logic uses content data.
- Story engine → Encounters: loads · Story and encounter logic uses content data.
- City game → Player: spawns · Main runtime instantiates player entity.
- City game → Enemy: spawns · Main runtime instantiates hostile entities.
- City game → Projectile: spawns · Main runtime manages projectile entities.
- City game → Background: layers · Gameplay uses a background art layer.
- City game → HUD: overlays · HUD is layered over the playfield.
- City game → Models: uses · Gameplay entities and runtime state use shared models.
- Sandbox launch → Sandbox ctrl: starts · Sandbox entry wires up its controller.
- Sandbox launch → Sandbox dungeon: opens · Sandbox entry opens the dungeon screen.
- Sandbox ctrl → Models: uses · Sandbox mechanics reuse shared domain types.
- Theme → Colors: includes · Theme builds on shared palette constants.
- Theme → Typography: includes · Theme builds on shared typography constants.
- Intro → Theme: styles with · Screens use the shared visual system.
- Game hub → Theme: styles with · Screens use the shared visual system.
- Combat → Theme: styles with · Screens use the shared visual system.
- City game → Story engine: syncs with · Real-time play consumes narrative/content state.
- Android → Main: launches · Platform host boots the Flutter entrypoint.
- iOS → Main: launches · Platform host boots the Flutter entrypoint.
- macOS → Main: launches · Platform host boots the Flutter entrypoint.