Project Scaffolding

Monorepo structure

The Saturn repository is a monorepo, not a single project. It contains multiple first-class projects unified by shared philosophy and tooling, each with distinct responsibility boundaries.

This organization reflects an intentional architecture: a cohesive ecosystem where the engine (saturn/), utilities (pieces/), tooling (codex/, docsgen/), sandbox (testbed/), and editor (editor/) coordinate around common design patterns while maintaining clear separation of concerns.

Top-level projects

The repository contains six major top-level projects:

• WIP pieces/ — STL-like header-only utility library
• saturn/ — Game engine core
• WIP codex/ — C++ source code parser
• WIP docsgen/ — Documentation generation tool
• Future metagen/ — Code generation tool
• Future editor/ — Saturn Editor (Flutter + native Saturn integration)
• testbed/ — Sandbox application for engine feature validation

The documentation website:

• docs/ — Astro 5 + Starlight documentation website (deployed to GitHub Pages)

And supporting directories:

• scripts/ — Build and development scripts
• cmake/ — CMake configuration and utilities
• assets/ — Shared assets (branding, design, etc.)
• Deprecated vendor/ — Third-party libraries (vendored dependencies, submodules soon to be replaced with CMake FetchContent)

---

General C++ project structure

Each C++ project follows a consistent directory structure:

• Directoryproject_name/ — Root source directory

  • Directoryinclude/project_name/ — Public headers

    • …
  • Directorysrc/ — Private source files

    • …
  • Directorytests/ — Unit and integration tests, fuzzing

    • Directoryunit/ — Unit tests

      • …
    • Directoryintegration/ — Integration tests

      • …
    • CMakeLists.txt — CMake build configuration
  • Directorybench/ — Benchmarks

    • …
  • CMakeLists.txt — CMake build configuration

In order to speed up compilation times targets may be split into multiple libraries that do not conform to the above structure for the sake of simplicity.

• Directoryproject_name/ — Root source directory

  • Directoryinclude/project_name/

    • Directorysub_project/ — Public headers for sub-project

      • …
  • Directorysrc/ — Private source files

    • Directorysub_project/ — Source files for sub-project

      • Directorytests/ — Unit and integration tests, fuzzing

        • …
      • Directorybench/ — Benchmarks

        • …
      • CMakeLists.txt — CMake build configuration for sub-project

---

General Flutter project structure

Each Flutter project follows a consistent directory structure:

• Directorylib/

  • main.dart — App entry point (minimal: runApp + bootstrap)
  • app.dart — Root widget (MaterialApp / MaterialApp.router)
  • Directorybootstrap/ — App startup & initialization

    • app_bootstrap.dart — Dependency initialization
    • bindings.dart — Service locator / DI wiring
    • env.dart — Environment config (dev, prod)
    • observers.dart — Global observers (Bloc, Navigator)
  • Directorycore/ — Framework-agnostic foundations

    • Directoryplatform/ — Platform abstractions (web, mobile, desktop)

      • …
    • Directoryerrors/ — Error types, failures, exception mapping

      • …
    • Directorylogging/ — Logging & crash reporting

      • …
    • Directoryutils/ — Pure utilities & extensions (no Flutter imports)

      • …
    • Directoryconstants/ — App-wide constants

      • …
    • Directorytypes/ — Shared typedefs & base interfaces

      • …
  • Directorydesign/ — Design system (no business logic)

    • Directorytokens/ — Colors, spacing, typography scales

      • …
    • Directorythemes/ — App themes (light/dark/high-contrast)

      • …
    • Directorycomponents/ — Reusable design components

      • …
    • Directoryicons/ — Custom icon definitions

      • …
  • Directoryshared/ — Cross-feature reusable Flutter code

    • Directorywidgets/ — Generic UI widgets (buttons, loaders)

      • …
    • Directorylayout/ — Responsive/layout helpers

      • …
    • Directorynavigation/ — App-level navigation abstractions

      • …
    • Directorystate/ — Shared state (auth session, app settings)

      • …
    • Directoryservices/ — Cross-cutting services (analytics, permissions)

      • …
  • Directoryfeatures/ — Feature-first vertical slices

    • Directoryproject_management/

      • Directorydata/

        • Directorymodels/ — DTOs & data models

          • …
        • Directorysources/ — Local / remote data sources

          • …
        • Directoryrepositories/ — Repository implementations

          • …
      • Directorydomain/

        • Directoryentities/ — Domain entities

          • …
        • Directoryrepositories/ — Repository interfaces

          • …
        • Directoryuse_cases/ — Business rules

          • …
      • Directorypresentation/

        • Directorypages/ — Screens

          • …
        • Directorywidgets/ — Feature-specific widgets

          • …
        • Directorystate/ — Cubit / Bloc / Notifier

          • …
        • routes.dart — Feature routes
      • feature.dart — Feature registration / exports
    • Directoryscene_editor/

      • Directorydata/

        • …
      • Directorydomain/

        • …
      • Directorypresentation/

        • …
      • feature.dart
  • Directorylocalization/ — i18n & l10n

    • app_localizations.dart
    • Directoryarb/

      • …

While this scales really well it can be a bit verbose for small features. In those cases feel free to collapse the data/domain/presentation layers into a single directory.

Smaller packages and tools may not require the full structure above. Use discretion to avoid unnecessary complexity.

---

pieces/ — Header-only utilities

• Type: C++23 header-only library
• Dependencies: utf8cpp (string utilities only)
• Responsibility: Core data structures and patterns shared across all Saturn projects

pieces/ provides STL-like utilities with zero runtime coupling to the engine:

• General purpose containers: SparseSet, TypelessVector, BitSet, CircularBuffer, ConstexprMap
• Memory allocators: PoolAllocator, ContiguousAllocator, ProxyAllocator
• Error handling: Result<T, E> and RefResult<T, E> for Railway-Oriented Programming
• Async utilities: Task<T> for C++20 coroutines
• String utilities: UTF-8 conversion, string_view helpers
• Performance tools: SIMD intrinsics wrappers, cache-line alignment

• Directorycontainers/ — SparseSet,, CircularBuffer, etc.

  • …
• Directorymemory/ — Allocators and pool memory management

  • …
• Directorycore/ — Result types, type traits, utility macros

  • …
• Directoryutils/ — Coroutines, SIMD, string utilities

  • …

---

saturn/ — Game engine core

• Type: Shared library (desktop/mobile), static library (web)
• Dependencies: pieces, Vulkan SDK, fmt, glm, glfw, nlohmann-json, etc.
• Responsibility: Rendering, input, execution, scene management, platform abstraction

The engine is organized into subsystems, each with clear ownership and invariants:

• Directorycore/ — Application lifecycle, system registry, events

  • …
• Directoryecs/ — Entity-Component-System (archetypal, type-erased)

  • …
• Directoryexec/ — ThreadPool, TaskFuture, TaskScheduler (async execution)

  • …
• Directorygraphics/ — RHI abstraction and high-level rendering API

  • …
• Directoryresources/ — Asset management and resource loading

  • …
• Directoryinput/ — Input system (three-layer architecture)

  • …
• Directorywindow/ — Window management abstraction

  • …
• Directoryplatform/ — Platform abstraction (Win32/POSIX/AGDK/Emscripten)

  • …
• Directoryscene/ — Scene graph (in development)

  • …

Core architecture

Entity-Component-System: Archetypal storage with type-erased components. Entities with identical component signatures live contiguously in the same archetype, maximizing data locality.

Multi-threaded execution: Work-stealing ThreadPool with TaskFuture<T> and TaskScheduler for dependency-based task graphs. Supports cancellation and worker affinity.

Rendering: Backend abstraction via RenderContext base class. Two implementations: Vulkan (desktop/mobile) and WebGPU (web + desktop via Dawn).

Input system: Three-layer architecture separating platform input sources, window-specific input context, and high-level action bindings.

Platform abstraction: Conditional compilation for Win32, POSIX (Linux), Android (AGDK), WebAssembly (Emscripten), and GLFW (cross-platform).

---

codex/ — C++ parser and documentation extractor

• Type: Static library
• Dependencies: pieces, tree-sitter, tree-sitter-cpp, fmt
• Responsibility: Parsing C++ source code and extracting structured documentation data

codex uses tree-sitter to build an Abstract Syntax Tree (AST) from C++ source files, then extracts structured information for documentation generation. It is intentionally decoupled from the Saturn engine and can parse any C++ project.

Note

Codex performs syntax-only analysis. It does not resolve types, instantiate templates, or evaluate preprocessor conditionals. This limitation keeps it simple and enables fast parsing of large codebases.

---

docsgen/ — Documentation generation tool

• Type: Executable (CLI tool)
• Dependencies: codex, bfgroup-lyra, STL
• Responsibility: Converting codex AST output into MDX documentation files

docsgen consumes codex output and generates MDX (Markdown + JSX) files suitable for the Astro documentation site. It is the pipeline terminal: FilesCollector → Parser → MDXGenerator.

Invocation:

./build/docsgen/docsgen --input ./saturn/include --output ./docs/src/content/docs/reference

This generates API reference pages from the engine headers. The tool guarantees deterministic output (same input = same output) and respects the --input and --output directories.

Note

API reference generation is in development. The MDXGenerator implementation is currently stubbed and awaits implementation.

---

testbed/ — Sandbox application

• Type: Executable application
• Dependencies: saturn, pieces
• Responsibility: Validating engine features and experimenting with APIs

testbed is a lightweight test application that links against saturn and exercises engine functionality. It serves as both a proof-of-concept and a safe sandbox for feature validation without disrupting the main codebase.

The testbed follows the standard Saturn application pattern: subclass Application, override lifecycle methods, and use SATURN_ENTRY_POINT(MyApp) for platform-specific entry point generation.

---

editor/ — Saturn Editor

• Type: Flutter application + native integration
• Dependencies: saturn (via FFI), Flutter SDK, Dart packages
• Responsibility: Interactive game development interface with native Saturn engine integration

The editor is deliberately built with a different technology stack (Flutter + Dart) to maintain separation from the C++ engine core. This architectural choice allows:

• Rapid UI iteration without affecting engine stability
• Clear native/managed boundary with explicit FFI bindings
• Independent release cycles for editor and engine
• Reusable Flutter packages for common editor widgets

Using Melos for monorepo management

The editor project uses Melos to manage multiple Flutter/Dart packages within the editor/ directory. Melos simplifies dependency management, versioning, and script execution across the monorepo.

Editor app (app/)

The main Saturn Editor application written in Flutter. It is a standard Flutter project with platform-specific implementations for Windows, Linux, and macOS.

Each feature owns its data layer, domain logic, and presentation layer. This structure enables independent feature development and testing.

Packages (packages/)

Note

The fl_nodes package is included as a Git submodule, allowing independent versioning and reuse in other projects.

The packages/ directory contains reusable Flutter/Dart libraries:

• fl_nodes — Node-based visual programming library (graph editor, node management, connections)
• Future packages — fl_panels, fl_inspector, fl_scene_viewport, etc.

These packages follow clean architecture with separate data, domain, and presentation layers. Each can be versioned independently and published to pub.dev for community use.

Tools (tools/)

Reserved for CLI tools and small standalone utilities useful for game development (currently empty, available for future expansion).

---

docs/ — Documentation website

• Type: Astro 5 + Starlight static site
• Deployment: GitHub Pages at /saturn/
• Responsibility: Engine and editor documentation for users and contributors

The documentation site is built with Astro (static site generator) and Starlight (documentation theme). It features:

• Multi-language support: English (en) and Italian (it)
• Mermaid diagrams: Pre-rendered to dual-theme SVG (light/dark mode)
• Custom React components: MermaidDiagram component with theme awareness
• Content collections: Type-safe MDX with frontmatter schema validation

• Directoryintro/ — Introduction and overview

  • …
• Directoryuser/ — User guides (WIP)

  • …
• Directorycollaborator/ — Contributor guides

  • …
• Directoryengineering/ — Design patterns and architecture

  • …
• Directoryreference/ — API reference (autogenerated)

  • …

Note

The documentation build process:

1. Write diagram code in src/mmds/*.mmd
2. Run pnpm run dev (includes Mermaid sync)
3. Reference diagram via <MermaidDiagram name="diagram_name" />
4. Pre-renderer generates dual-theme SVGs automatically
5. React component displays theme-aware SVG on page load

All diagrams are pre-rendered to static SVG. No client-side Mermaid library is shipped, keeping the bundle size minimal.

---

Dependency hierarchy

The monorepo maintains a strict dependency hierarchy to prevent cycles and enforce modularity: