# gjmcn/atomic-agents architecture

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

- Interactive diagram: https://gitdiagram.com/gjmcn/atomic-agents
- Repository: https://github.com/gjmcn/atomic-agents

## Overview

##### Project Type and Purpose
- Atomic Agents is an open-source JavaScript module (npm package) for spatial agent-based modeling.
- It provides a collection of geometry utilities, spatial region functions, random-sampling, and simulation primitives (agents, actors, zones).

##### File Structure Analysis
- Top-level files: configuration (`package.json`, `.gitignore`), licensing (`LICENSE`), changelog, README.
- `src/` directory: the core implementation broken into multiple ES modules:
- Geometry & vector math (`vector.js`, `polyline.js`, `boundary-distance.js`, etc.)
- Spatial constructs (`grid.js`, `regions.js`, `zone.js`, `autotile.js`)
- Random sampling & helpers (`random.js`, `random-circles.js`, `helpers.js`)
- Simulation primitives (`agent.js`, `actor.js`, `simulation.js`)
- Entry point (`index.js`) exporting the public API.
- `__tests__/`: unit tests for every major function/module.
- `docs/`: static site with API reference and examples.

##### Insights from README
- The package is intended for interactive spatial simulations (e.g., disease spread models).
- No external services—pure client or Node.js library.
- Extensible API for plugging in custom agent behaviors and geometry-based interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Public API Layer"
        API["index.js\n(Public API)"]:::runtime
    end

    subgraph "Simulation Core"
        Sim["simulation.js\n(Core Engine)"]:::runtime
        Agent["agent.js"]:::runtime
        Actor["actor.js"]:::runtime
    end

    subgraph "Spatial & Geometry Layer"
        Vec["vector.js"]:::runtime
        Poly["polyline.js"]:::runtime
        BD["boundary-distance.js"]:::runtime
        CD["centroid-distance.js"]:::runtime
        IDist["inside-distance.js"]:::runtime
        CW["centroid-within.js"]:::runtime
        W["within.js"]:::runtime
        Over["overlap.js"]:::runtime
        Reg["regions.js"]:::runtime
        Grid["grid.js"]:::runtime
        Zone["zone.js"]:::runtime
        Auto["autotile.js"]:::runtime
        Simp["simplify.js"]:::runtime
        Sq["square.js"]:::runtime
        Xset["x-set.js"]:::runtime
    end

    subgraph "Utility Layer"
        Rand["random.js"]:::runtime
        RCirc["random-circles.js"]:::runtime
        Help["helpers.js"]:::runtime
        FF["from-functions.js"]:::runtime
    end

    subgraph "Non-Runtime"
        Tests["__tests__/*.js\n(Unit Tests)"]:::non
        Docs["docs/\n(Documentation)"]:::non
    end

    %% Connections
    API -->|"new Simulation() / createAgent()"| Sim
    API -->|"exports"| Agent
    API -->|"exports"| Actor
    API -->|"exports"| Vec

    Sim -->|"uses geometry"| Vec
    Sim -->|"uses geometry"| Poly
    Sim -->|"uses geometry"| BD
    Sim -->|"uses geometry"| CD
    Sim -->|"uses geometry"| IDist
    Sim -->|"uses geometry"| CW
    Sim -->|"uses geometry"| W
    Sim -->|"uses geometry"| Over
    Sim -->|"uses geometry"| Reg
    Sim -->|"uses geometry"| Grid
    Sim -->|"uses geometry"| Zone
    Sim -->|"uses geometry"| Auto
    Sim -->|"uses geometry"| Simp
    Sim -->|"uses geometry"| Sq
    Sim -->|"uses geometry"| Xset

    Sim -->|"random sampling"| Rand
    Sim -->|"random circle sampling"| RCirc
    Sim -->|"helpers support"| Help
    Sim -.->|"user callbacks"| FF

    Help -.->|"shared utility"| Vec

    %% Click Events
    click API "https://github.com/gjmcn/atomic-agents/blob/main/src/index.js"
    click Agent "https://github.com/gjmcn/atomic-agents/blob/main/src/agent.js"
    click Actor "https://github.com/gjmcn/atomic-agents/blob/main/src/actor.js"
    click Sim "https://github.com/gjmcn/atomic-agents/blob/main/src/simulation.js"
    click Vec "https://github.com/gjmcn/atomic-agents/blob/main/src/vector.js"
    click Poly "https://github.com/gjmcn/atomic-agents/blob/main/src/polyline.js"
    click BD "https://github.com/gjmcn/atomic-agents/blob/main/src/boundary-distance.js"
    click CD "https://github.com/gjmcn/atomic-agents/blob/main/src/centroid-distance.js"
    click IDist "https://github.com/gjmcn/atomic-agents/blob/main/src/inside-distance.js"
    click CW "https://github.com/gjmcn/atomic-agents/blob/main/src/centroid-within.js"
    click W "https://github.com/gjmcn/atomic-agents/blob/main/src/within.js"
    click Over "https://github.com/gjmcn/atomic-agents/blob/main/src/overlap.js"
    click Reg "https://github.com/gjmcn/atomic-agents/blob/main/src/regions.js"
    click Grid "https://github.com/gjmcn/atomic-agents/blob/main/src/grid.js"
    click Zone "https://github.com/gjmcn/atomic-agents/blob/main/src/zone.js"
    click Auto "https://github.com/gjmcn/atomic-agents/blob/main/src/autotile.js"
    click Simp "https://github.com/gjmcn/atomic-agents/blob/main/src/simplify.js"
    click Sq "https://github.com/gjmcn/atomic-agents/blob/main/src/square.js"
    click Xset "https://github.com/gjmcn/atomic-agents/blob/main/src/x-set.js"
    click Rand "https://github.com/gjmcn/atomic-agents/blob/main/src/random.js"
    click RCirc "https://github.com/gjmcn/atomic-agents/blob/main/src/random-circles.js"
    click Help "https://github.com/gjmcn/atomic-agents/blob/main/src/helpers.js"
    click FF "https://github.com/gjmcn/atomic-agents/blob/main/src/from-functions.js"
    click Tests "https://github.com/gjmcn/atomic-agents/tree/main/__tests__"
    click Docs "https://github.com/gjmcn/atomic-agents/tree/main/docs/"

    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef non fill:#D3D3D3,stroke:#000,stroke-width:1px
```
