# zenix-s/philosophers architecture

> Architecture diagram of the GitHub repository zenix-s/philosophers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zenix-s/philosophers
- Repository: https://github.com/zenix-s/philosophers

## Overview

##### Main Components
- Philosopher Entities: Represent individual philosophers. In the code, these are managed in the "philosopher" directory with routines for eating, sleeping, etc.
- Simulation Manager / State Machine: The “state_machine” folder indicates the use of a state machine to handle the different states (e.g., initialization, simulation start, error handling). This component is central to controlling the simulation’s life cycle.
- Simulation States: There are distinct states defined in the “states” directory:
- Validation State – ensuring that the correct arguments are provided.
- Creation States – initialization of global state, creation of forks, and philosophers.
- Running States – starting the simulation, monitoring simulation progress, and joining threads once the simulation ends.
- Error States – managing any simulation or initialization errors.
- Shared Utilities: The “shared” directory contains utility functions (for logging, timestamping, checking if a philosopher has eaten enough, etc.) that support the simulation.
- Domain and Global Definitions: Files in the “include” directory (domain.h, global.h, philosophers.h) define the core data structures and constants used across the simulation.

##### Relationships and Interactions
- The Main Flow starts with validating arguments (using validate_arguments_state), then proceeds to set up the global simulation state.
- There’s an initialization phase creating the forks and philosophers (via respective states in the “states” directory).
- Once the simulation is started, each philosopher (running in its own thread) utilizes routines from the “philosopher” subdirectory to switch between actions (eating, sleeping, and possibly thinking, though mostly implied).
- A central monitor (implemented in monitor_simulation_state) observes the simulation progress, ensuring that rules (like a philosopher “dying” or having eaten the required meals) are enforced.
- At the completion of the simulation, the state machine transitions errors or cleanup states such as join_threads_state and destroy_simulation_state.
- The utility functions in the “shared” folder offer common services like logging and time-tracking across various states.

##### Architectural Patterns and Design Principles
- Modular Design: Different simulation phases are encapsulated in different state files/subdirectories (e.g. validation, creation, joining, and error).
- State Machine Pattern: The system uses a state machine to transition through various simulation phases, ensuring a clear separation of responsibilities.
- Separation of Concerns: Utility functions, state management, and domain definitions are all clearly separated.
- Concurrency: The simulation likely implements multi-threading (abstract inference from “join_threads_state” and “philosopher routines”) to mimic concurrent philosopher actions.

##### Final Touches – What
- Clear labels for each component (e.g., “Main”, “State Machine Factory”, “Philosopher Routine”, “Utility Functions”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation State Machine"
        A1["Validation State"]:::core
        A2["Global State Creation"]:::core
        A3["Forks & Philosophers Initialization"]:::core
        A4["Monitor Simulation"]:::core
        A5["Thread Joining & Cleanup"]:::core
        A6["Error Handling"]:::error
    end

    subgraph "Philosopher Entities"
        PH1["Philosopher Routine"]:::philo
        PH2["Eating State"]:::philo
        PH3["Sleeping State"]:::philo
    end

    subgraph "Simulation Manager"
        SM1["State Machine Factory"]:::manager
        SM2["Set Machine Error"]:::manager
    end

    subgraph "Utilities & Definitions"
        U1["Shared Utilities"]:::utility
        D1["Domain & Global Definitions"]:::domain
    end

    %% Flow Connections
    A1 --> A2
    A2 --> A3
    A3 -->|"StartsThreads"| PH1
    A3 --> A4
    PH1 -->|"SwitchesTo"| PH2
    PH1 -->|"SwitchesTo"| PH3
    A4 --> A5
    A4 --> A6
    A4 --> PH1

    SM1 --> A1
    SM1 --> A2
    SM2 --> A6

    U1 --- A1
    U1 --- A2
    U1 --- PH1

    D1 --- A2
    D1 --- PH1

    %% Click Events
    click PH1 "https://github.com/zenix-s/philosophers/blob/main/philo/src/philosopher/philosopher_routine.c"
    click PH2 "https://github.com/zenix-s/philosophers/blob/main/philo/src/philosopher/philosopher_eat_state.c"
    click PH3 "https://github.com/zenix-s/philosophers/blob/main/philo/src/philosopher/philosopher_sleep_state.c"

    click SM1 "https://github.com/zenix-s/philosophers/blob/main/philo/src/state_machine/state_machine_factory.c"
    click SM2 "https://github.com/zenix-s/philosophers/blob/main/philo/src/state_machine/set_machine_error.c"

    click A1 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/validation/validate_arguments_state.c"
    click A2 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/global/create_global_state.c"
    click A3 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/create_forks_state.c"
    click A4 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/monitor_simulation_state.c"
    click A5 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/join_threads_state.c"
    click A6 "https://github.com/zenix-s/philosophers/blob/main/philo/src/states/error/error_state.c"

    click U1 "https://github.com/zenix-s/philosophers/tree/main/philo/src/shared"
    click D1 "https://github.com/zenix-s/philosophers/tree/main/philo/include"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef philo fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef manager fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef domain fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef error fill:#FF6347,stroke:#000,stroke-width:2px;
```
