# joonspk-research/generative_agents architecture

> Architecture diagram of the GitHub repository joonspk-research/generative_agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joonspk-research/generative_agents
- Repository: https://github.com/joonspk-research/generative_agents

## Overview

Generative Agents is a research simulation for believable human behavior in a Smallville-like game world. The documented workflow is to start the Django environment and simulation server, fork or name a simulation, run game steps, and view the agents in a browser; saved runs can be replayed or compressed for demos. The README also describes agent-history customization. Simulation internals and frontend views are not present in the supplied excerpts, so their relationships are omitted or marked unverified; paths for these subsystems use only directories shown in the tree.

Main entry points: [`reverie/backend_server`](https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server) (Simulation server), [`environment/frontend_server`](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server) (Django environment), [`reverie/compress_sim_storage.py`](https://github.com/joonspk-research/generative_agents/blob/main/reverie/compress_sim_storage.py) (Demo compression), [`environment/frontend_server/storage`](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/storage) (Saved simulations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Agent simulation"]
  node_sim_server["Simulation server"]
  node_agents["Generative agents"]
  node_agent_memory[("Agent memory")]
  node_agent_actions["Agent actions"]
  node_agent_history["Agent history"]
end

subgraph group_environment["World environment"]
  node_environment_server["Django environment"]
  node_environment_views["Environment views"]
  node_world_assets["World assets"]
  node_replay_demo["Replay and demo"]
  node_url_routes["URL routes<br/>[urls.py]"]
end

subgraph group_persistence["Simulation persistence"]
  node_simulation_storage[("Saved simulations")]
  node_compressed_storage[("Compressed demos")]
  node_compression["Demo compression"]
  node_global_methods["Shared file utilities<br/>[global_methods.py]"]
end

subgraph group_configuration["Configuration"]
  node_base_settings["Base settings<br/>[base.py]"]
  node_local_settings["Local settings<br/>[local.py]"]
  node_settings_selector["Settings selector<br/>[__init__.py]"]
end

node_user(("Operator"))
node_browser(("Browser user"))
node_openai["OpenAI API"]

node_user -->|"starts and runs"| node_sim_server
node_user -->|"starts"| node_environment_server
node_browser -->|"opens simulator"| node_environment_server
node_url_routes -->|"routes requests"| node_environment_views
node_sim_server -.->|"runs steps"| node_agents
node_agents -.->|"uses memory"| node_agent_memory
node_agents -.->|"produces actions"| node_agent_actions
node_sim_server -.->|"exchanges state"| node_environment_server
node_environment_server -.->|"serves world"| node_world_assets
node_sim_server -.->|"requests completions"| node_openai
node_sim_server -->|"saves runs"| node_simulation_storage
node_replay_demo -->|"reads runs"| node_simulation_storage
node_compression -->|"reads run data"| node_simulation_storage
node_compression -->|"writes demo data"| node_compressed_storage
node_compression -->|"uses file helpers"| node_global_methods
node_replay_demo -->|"reads demo data"| node_compressed_storage
node_agents -.->|"loads history"| node_agent_history
node_settings_selector -->|"imports settings"| node_base_settings
node_settings_selector -->|"imports settings"| node_local_settings

click node_sim_server "https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server"
click node_agents "https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server"
click node_agent_memory "https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server"
click node_agent_actions "https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server"
click node_environment_server "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server"
click node_environment_views "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server"
click node_world_assets "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/static_dirs/assets/the_ville"
click node_simulation_storage "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/storage"
click node_compressed_storage "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/compressed_storage"
click node_compression "https://github.com/joonspk-research/generative_agents/blob/main/reverie/compress_sim_storage.py"
click node_agent_history "https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/static_dirs/assets/the_ville/agent_history_init_n25.csv"
click node_replay_demo "https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server"
click node_global_methods "https://github.com/joonspk-research/generative_agents/blob/main/reverie/global_methods.py"
click node_base_settings "https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/base.py"
click node_local_settings "https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/local.py"
click node_settings_selector "https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/__init__.py"
click node_url_routes "https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/urls.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sim_server,node_agents,node_agent_memory,node_agent_actions,node_agent_history,node_browser toneBlue
class node_environment_server,node_environment_views,node_world_assets,node_replay_demo,node_url_routes toneAmber
class node_simulation_storage,node_compressed_storage,node_compression,node_global_methods,node_openai toneMint
class node_base_settings,node_local_settings,node_settings_selector toneRose
class node_user toneIndigo
```

## Components

### Agent simulation

- [Simulation server](https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server): `reverie/backend_server`
- [Generative agents](https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server): `reverie/backend_server`
- [Agent memory](https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server): `reverie/backend_server`
- [Agent actions](https://github.com/joonspk-research/generative_agents/tree/main/reverie/backend_server): `reverie/backend_server`
- [Agent history](https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/static_dirs/assets/the_ville/agent_history_init_n25.csv): `environment/frontend_server/static_dirs/assets/the_ville/agent_history_init_n25.csv`

### World environment

- [Django environment](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server): `environment/frontend_server`
- [Environment views](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server): `environment/frontend_server`
- [World assets](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/static_dirs/assets/the_ville): `environment/frontend_server/static_dirs/assets/the_ville`
- [Replay and demo](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server): `environment/frontend_server`
- [URL routes](https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/urls.py): `environment/frontend_server/frontend_server/urls.py`

### Simulation persistence

- [Saved simulations](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/storage): `environment/frontend_server/storage`
- [Compressed demos](https://github.com/joonspk-research/generative_agents/tree/main/environment/frontend_server/compressed_storage): `environment/frontend_server/compressed_storage`
- [Demo compression](https://github.com/joonspk-research/generative_agents/blob/main/reverie/compress_sim_storage.py): `reverie/compress_sim_storage.py`
- [Shared file utilities](https://github.com/joonspk-research/generative_agents/blob/main/reverie/global_methods.py): `reverie/global_methods.py`

### Configuration

- [Base settings](https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/base.py): `environment/frontend_server/frontend_server/settings/base.py`
- [Local settings](https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/local.py): `environment/frontend_server/frontend_server/settings/local.py`
- [Settings selector](https://github.com/joonspk-research/generative_agents/blob/main/environment/frontend_server/frontend_server/settings/__init__.py): `environment/frontend_server/frontend_server/settings/__init__.py`

### Other components

- **Operator**
- **Browser user**
- **OpenAI API**

## Connections

- Operator → Simulation server: starts and runs (evidence: `README.md`)
- Operator → Django environment: starts (evidence: `README.md`)
- Browser user → Django environment: opens simulator (evidence: `README.md`)
- URL routes → Environment views: routes requests (evidence: `environment/frontend_server/frontend_server/urls.py`)
- Simulation server → Generative agents: runs steps
- Generative agents → Agent memory: uses memory
- Generative agents → Agent actions: produces actions
- Simulation server → Django environment: exchanges state
- Django environment → World assets: serves world
- Simulation server → OpenAI API: requests completions
- Simulation server → Saved simulations: saves runs (evidence: `README.md`)
- Replay and demo → Saved simulations: reads runs (evidence: `README.md`)
- Demo compression → Saved simulations: reads run data (evidence: `reverie/compress_sim_storage.py`)
- Demo compression → Compressed demos: writes demo data (evidence: `reverie/compress_sim_storage.py`)
- Demo compression → Shared file utilities: uses file helpers (evidence: `reverie/compress_sim_storage.py`)
- Replay and demo → Compressed demos: reads demo data (evidence: `README.md`)
- Generative agents → Agent history: loads history (evidence: `README.md`)
- Settings selector → Base settings: imports settings (evidence: `environment/frontend_server/frontend_server/settings/__init__.py`)
- Settings selector → Local settings: imports settings (evidence: `environment/frontend_server/frontend_server/settings/__init__.py`)
