# hashtopolis/server architecture

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

- Interactive diagram: https://gitdiagram.com/hashtopolis/server
- Repository: https://github.com/hashtopolis/server

## Overview

Hashtopolis is a multi-platform client-server system for distributing hashcat work across computers, with multi-user and group management. The main workflow is users organizing hash data and cracking work in the server, which assigns work to agents; agents report progress and results. The graph also includes the web interface, both documented API surfaces, permissions, and the persistence layer. Some connections reflect README-level product behavior; source excerpts and the index show additional internal relationships, but many runtime routes were not sampled.

Main entry points: [`src/index.php`](https://github.com/hashtopolis/server/blob/master/src/index.php) (Web Pages), [`src/dba/AbstractModelFactory.php`](https://github.com/hashtopolis/server/blob/master/src/dba/AbstractModelFactory.php) (Model Persistence), [`src/tasks.php`](https://github.com/hashtopolis/server/blob/master/src/tasks.php) (Work Setup), [`src/inc/Login.php`](https://github.com/hashtopolis/server/blob/master/src/inc/Login.php) (Session Login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Cracking Workflow"]
  node_work_setup["Work Setup<br/>[tasks.php]"]
  node_hash_data["Hash Data<br/>[HashlistUtils.php]"]
  node_task_models["Task Models<br/>[Task.php]"]
end

subgraph group_agent["Agent Communication"]
  node_agent_client(("Cracking Agents"))
  node_agent_api["Agent API<br/>[AgentApiApp.php]"]
  node_agent_actions["Agent Actions<br/>[GetTaskAction.php]"]
  node_agent_state["Agent State<br/>[Agent.php]"]
  node_agent_models["Agent Protocol<br/>[PQuery.php]"]
end

subgraph group_users["Users And UI"]
  node_web_pages["Web Pages<br/>[index.php]"]
  node_session_login["Session Login<br/>[Login.php]"]
  node_access_control["Access Control<br/>[AccessControl.php]"]
  node_template_render["Template Rendering<br/>[Template.php]"]
end

subgraph group_api["API Surfaces"]
  node_user_api["User API<br/>[UserAPIBasic.php]"]
  node_v2_api["API v2<br/>[ApiRegistry.php]"]
end

subgraph group_data["Persistence"]
  node_factory_registry["Factory Registry<br/>[Factory.php]"]
  node_query_filters["Query Filters<br/>[QueryFilter.php]"]
  node_model_factory["Model Persistence"]
  node_model_records["Domain Records<br/>[AccessGroup.php]"]
  node_database[("Database")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_web_pages
node_web_pages -->|"authenticates"| node_session_login
node_session_login -->|"loads sessions"| node_factory_registry
node_web_pages -->|"renders"| node_template_render
node_web_pages -->|"manages work"| node_work_setup
node_work_setup -->|"creates tasks"| node_task_models
node_work_setup -->|"uses hashlists"| node_hash_data
node_agent_client -->|"requests work"| node_agent_api
node_agent_api -.->|"dispatches actions"| node_agent_actions
node_agent_actions -.->|"uses agent state"| node_agent_state
node_agent_client -.->|"exchanges protocol"| node_agent_models
node_operator -.->|"calls"| node_user_api
node_operator -.->|"calls"| node_v2_api
node_access_control -->|"checks login"| node_session_login
node_factory_registry -->|"provides factories"| node_model_factory
node_model_factory -->|"applies filters"| node_query_filters
node_model_factory -->|"reads and writes"| node_database
node_model_factory -.->|"hydrates records"| node_model_records

click node_work_setup "https://github.com/hashtopolis/server/blob/master/src/tasks.php"
click node_hash_data "https://github.com/hashtopolis/server/blob/master/src/inc/utils/HashlistUtils.php"
click node_task_models "https://github.com/hashtopolis/server/blob/master/src/dba/models/Task.php"
click node_agent_api "https://github.com/hashtopolis/server/blob/master/src/inc/agentapi/AgentApiApp.php"
click node_agent_actions "https://github.com/hashtopolis/server/blob/master/src/inc/agentapi/model/GetTaskAction.php"
click node_agent_state "https://github.com/hashtopolis/server/blob/master/src/dba/models/Agent.php"
click node_web_pages "https://github.com/hashtopolis/server/blob/master/src/index.php"
click node_session_login "https://github.com/hashtopolis/server/blob/master/src/inc/Login.php"
click node_access_control "https://github.com/hashtopolis/server/blob/master/src/inc/utils/AccessControl.php"
click node_template_render "https://github.com/hashtopolis/server/blob/master/src/inc/templating/Template.php"
click node_user_api "https://github.com/hashtopolis/server/blob/master/src/inc/user_api/UserAPIBasic.php"
click node_v2_api "https://github.com/hashtopolis/server/blob/master/src/inc/apiv2/common/ApiRegistry.php"
click node_agent_models "https://github.com/hashtopolis/server/blob/master/src/inc/agent/PQuery.php"
click node_factory_registry "https://github.com/hashtopolis/server/blob/master/src/dba/Factory.php"
click node_query_filters "https://github.com/hashtopolis/server/blob/master/src/dba/QueryFilter.php"
click node_model_factory "https://github.com/hashtopolis/server/blob/master/src/dba/AbstractModelFactory.php"
click node_model_records "https://github.com/hashtopolis/server/blob/master/src/dba/models/AccessGroup.php"

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_work_setup,node_hash_data,node_task_models toneBlue
class node_agent_client,node_agent_api,node_agent_actions,node_agent_state,node_agent_models toneAmber
class node_web_pages,node_session_login,node_access_control,node_template_render toneMint
class node_user_api,node_v2_api toneRose
class node_factory_registry,node_query_filters,node_model_factory,node_model_records,node_database,node_operator toneIndigo
```

## Components

### Cracking Workflow

- [Work Setup](https://github.com/hashtopolis/server/blob/master/src/tasks.php): `src/tasks.php`
- [Hash Data](https://github.com/hashtopolis/server/blob/master/src/inc/utils/HashlistUtils.php): `src/inc/utils/HashlistUtils.php`
- [Task Models](https://github.com/hashtopolis/server/blob/master/src/dba/models/Task.php): `src/dba/models/Task.php`

### Agent Communication

- **Cracking Agents**
- [Agent API](https://github.com/hashtopolis/server/blob/master/src/inc/agentapi/AgentApiApp.php): `src/inc/agentapi/AgentApiApp.php`
- [Agent Actions](https://github.com/hashtopolis/server/blob/master/src/inc/agentapi/model/GetTaskAction.php): `src/inc/agentapi/model/GetTaskAction.php`
- [Agent State](https://github.com/hashtopolis/server/blob/master/src/dba/models/Agent.php): `src/dba/models/Agent.php`
- [Agent Protocol](https://github.com/hashtopolis/server/blob/master/src/inc/agent/PQuery.php): `src/inc/agent/PQuery.php`

### Users And UI

- [Web Pages](https://github.com/hashtopolis/server/blob/master/src/index.php): `src/index.php`
- [Session Login](https://github.com/hashtopolis/server/blob/master/src/inc/Login.php): `src/inc/Login.php`
- [Access Control](https://github.com/hashtopolis/server/blob/master/src/inc/utils/AccessControl.php): `src/inc/utils/AccessControl.php`
- [Template Rendering](https://github.com/hashtopolis/server/blob/master/src/inc/templating/Template.php): `src/inc/templating/Template.php`

### API Surfaces

- [User API](https://github.com/hashtopolis/server/blob/master/src/inc/user_api/UserAPIBasic.php): `src/inc/user_api/UserAPIBasic.php`
- [API v2](https://github.com/hashtopolis/server/blob/master/src/inc/apiv2/common/ApiRegistry.php): `src/inc/apiv2/common/ApiRegistry.php`

### Persistence

- [Factory Registry](https://github.com/hashtopolis/server/blob/master/src/dba/Factory.php): `src/dba/Factory.php`
- [Query Filters](https://github.com/hashtopolis/server/blob/master/src/dba/QueryFilter.php): `src/dba/QueryFilter.php`
- [Model Persistence](https://github.com/hashtopolis/server/blob/master/src/dba/AbstractModelFactory.php): `src/dba/AbstractModelFactory.php`
- [Domain Records](https://github.com/hashtopolis/server/blob/master/src/dba/models/AccessGroup.php): `src/dba/models/AccessGroup.php`
- **Database**

### Other components

- **Operator**

## Connections

- Operator → Web Pages: uses
- Web Pages → Session Login: authenticates (evidence: `src/inc/Login.php`)
- Session Login → Factory Registry: loads sessions (evidence: `src/inc/Login.php`)
- Web Pages → Template Rendering: renders
- Web Pages → Work Setup: manages work
- Work Setup → Task Models: creates tasks (evidence: `src/tasks.php`)
- Work Setup → Hash Data: uses hashlists (evidence: `src/tasks.php`)
- Cracking Agents → Agent API: requests work
- Agent API → Agent Actions: dispatches actions
- Agent Actions → Agent State: uses agent state
- Cracking Agents → Agent Protocol: exchanges protocol
- Operator → User API: calls
- Operator → API v2: calls
- Access Control → Session Login: checks login (evidence: `src/inc/utils/AccessControl.php`)
- Factory Registry → Model Persistence: provides factories (evidence: `src/dba/Factory.php`)
- Model Persistence → Query Filters: applies filters (evidence: `src/dba/AbstractModelFactory.php`)
- Model Persistence → Database: reads and writes (evidence: `src/dba/AbstractModelFactory.php`)
- Model Persistence → Domain Records: hydrates records