# amarqs/philosophers architecture

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

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

## Overview

##### Project type and purpose
- This is an educational C‐based concurrency simulation implementing the classic “Dining Philosophers” problem.
- The mandatory version uses pthreads and mutexes; each philosopher is a thread, each fork is protected by a mutex.
- The goal is to model philosopher states (thinking, eating, sleeping), safe fork acquisition/release, and detect starvation.

##### File structure
- Top level:
- Makefile, philo/ directory containing ./include and ./src
- philo/include/philo.h: central structs (philosopher, fork mutex array, timing, shared data)
- philo/src modules:
- main.c & init.c: parse args, initialize data, spawn threads
- thread.c & routine.c: philosopher thread creation and lifecycle loop
- actions.c: grab forks, eat, sleep, think
- monitors.c & check.c: watcher threads/functions that detect death
- utils.c & basic_functions.c: time helpers, printing/logging
- errors.c: error reporting, graceful exit
- Build artifacts guided by Makefile rules (all, clean, fclean, re).

##### README for additional insights
- Describes command-line args, allowed library functions, expected console logs.
- Emphasizes no data races, accurate timing, correct mutex usage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Controller"
        MC["Main Controller"]:::controller
    end

    subgraph "Threads"
        Ph["Philosopher #i (Thread)"]:::thread
        Mon["Monitor (Thread)"]:::monitor
    end

    subgraph "Resources & I/O"
        Forks["Fork Mutex Array"]:::mutex
        Log["Logger (Protected I/O)"]:::logger
    end

    subgraph "Utilities & Data"
        Utils["Utility/Time Subsystem"]:::util
        Err["Error Reporting & Exit Handler"]:::error
        Data["Shared Data Structures & Config"]:::data
    end

    MC -->|"spawn threads"| Ph
    MC -->|"spawn monitor"| Mon
    MC -->|"initialize shared data"| Data
    MC -->|"initialize timing subsystem"| Utils

    Ph -->|"lock/unlock forks"| Forks
    Ph -->|"state event"| Log
    Ph -->|"error handling"| Err

    Mon -->|"death event"| Log
    Mon -->|"check times via"| Utils

    classDef controller fill:#B3CDE3,stroke:#011f4b,color:#011f4b;
    classDef thread fill:#C7E9C0,stroke:#00441B,color:#00441B;
    classDef monitor fill:#FDD0A2,stroke:#8C2D04,color:#8C2D04;
    classDef mutex fill:#E5F5E0,stroke:#238B45,color:#238B45,shape:cylinder;
    classDef logger fill:#FEE0D2,stroke:#A63603,color:#A63603;
    classDef util fill:#D7B5D8,stroke:#581845,color:#581845;
    classDef error fill:#FEE6CE,stroke:#7F2704,color:#7F2704;
    classDef data fill:#FFFFCC,stroke:#666600,color:#666600;

    click MC "https://github.com/amarqs/philosophers/blob/main/philo/src/main.c"
    click Ph "https://github.com/amarqs/philosophers/blob/main/philo/src/thread.c"
    click Forks "https://github.com/amarqs/philosophers/blob/main/philo/include/philo.h"
    click Mon "https://github.com/amarqs/philosophers/blob/main/philo/src/monitors.c"
    click Log "https://github.com/amarqs/philosophers/blob/main/philo/src/basic_functions.c"
    click Utils "https://github.com/amarqs/philosophers/blob/main/philo/src/utils.c"
    click Err "https://github.com/amarqs/philosophers/blob/main/philo/src/errors.c"
    click Data "https://github.com/amarqs/philosophers/blob/main/philo/include/philo.h"
```
