# atk4/data architecture

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

- Interactive diagram: https://gitdiagram.com/atk4/data
- Repository: https://github.com/atk4/data

## Overview

ATK Data is a PHP business-data modeling and persistence library: applications define models, fields, scopes and relations, then load, query or mutate datasets through a persistence backend. The README highlights aggregation, database-agnostic backends, generic UI/API integration and extensible user actions; the graph preserves those capabilities without implying integrations are built into this repository. Edges cite shown calls, imports/reference-index evidence or README statements; unsampled subsystems use their exact tree paths and documented links are distinguished.

Main entry points: [`src/Persistence.php`](https://github.com/atk4/data/blob/develop/src/Persistence.php) (Persistence contract), [`src/Model.php`](https://github.com/atk4/data/blob/develop/src/Model.php) (Data model), [`src/Persistence/Sql.php`](https://github.com/atk4/data/blob/develop/src/Persistence/Sql.php) (SQL persistence), [`src/Persistence/Array_.php`](https://github.com/atk4/data/blob/develop/src/Persistence/Array_.php) (Array persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Business modeling"]
  node_model["Data model<br/>[Model.php]"]
  node_field["Fields<br/>[Field.php]"]
  node_validation["Email field<br/>[EmailField.php]"]
  node_relation["Model relations<br/>[Reference.php]"]
  node_relation_kinds["Relation types<br/>[HasMany.php]"]
  node_join["Join configuration<br/>[Join.php]"]
  node_user_actions["User actions<br/>[UserAction.php]"]
end

subgraph group_query["Query and expressions"]
  node_scope["Scopes and filters<br/>[Scope.php]"]
  node_condition["Conditions<br/>[Condition.php]"]
  node_sql_field["SQL expression fields"]
  node_expression["SQL expressions<br/>[Expression.php]"]
  node_query_builder["SQL query builder<br/>[Query.php]"]
  node_aggregate["Aggregate models<br/>[AggregateModel.php]"]
end

subgraph group_persistence["Persistence backends"]
  node_persistence_base["Persistence contract<br/>[Persistence.php]"]
  node_array_backend["Array persistence<br/>[Array_.php]"]
  node_array_table[("Array tables<br/>[Table.php]")]
  node_array_actions["Array actions<br/>[Action.php]"]
  node_sql_backend["SQL persistence<br/>[Sql.php]"]
  node_sql_connection["SQL connection<br/>[Connection.php]"]
  node_sql_dialects["SQL dialects"]
  node_csv["CSV persistence<br/>[Csv.php]"]
  node_static_backend["Static persistence<br/>[Static_.php]"]
end

subgraph group_schema["Schema and types"]
  node_migrator["Schema migration<br/>[Migrator.php]"]
  node_types["Type handling<br/>[Types.php]"]
end

subgraph group_integration["Application integration"]
  node_ui["Agile UI"]
  node_api["Agile API"]
end

node_app(("Application code"))
node_sql_server[("SQL database")]
node_external_data[("NoSQL or API source")]

node_app -->|"defines"| node_model
node_model -->|"adds fields"| node_field
node_model -->|"builds scopes"| node_scope
node_scope -->|"contains conditions"| node_condition
node_model -->|"defines relations"| node_relation
node_relation -->|"uses relation types"| node_relation_kinds
node_model -->|"configures joins"| node_join
node_app -->|"requests aggregates"| node_aggregate
node_aggregate -.->|"extends model behavior"| node_model
node_sql_field -->|"builds expressions"| node_expression
node_condition -->|"accepts expressions"| node_expression
node_model -->|"uses persistence"| node_persistence_base
node_persistence_base -->|"typecasts fields"| node_types
node_persistence_base -.->|"supports backends"| node_array_backend
node_array_backend -->|"stores rows"| node_array_table
node_array_backend -.->|"executes actions"| node_array_actions
node_persistence_base -.->|"supports backends"| node_sql_backend
node_sql_backend -->|"builds queries"| node_query_builder
node_sql_backend -->|"uses connection"| node_sql_connection
node_sql_backend -->|"creates expression fields"| node_sql_field
node_query_builder -->|"renders expressions"| node_expression
node_sql_connection -.->|"connects to"| node_sql_server
node_sql_backend -.->|"supports dialects"| node_sql_dialects
node_persistence_base -.->|"supports backends"| node_csv
node_persistence_base -.->|"supports backends"| node_static_backend
node_app -.->|"migrates schema"| node_migrator
node_app -.->|"defines actions"| node_user_actions
node_app -.->|"binds model"| node_ui
node_app -.->|"exposes endpoint"| node_api
node_persistence_base -.->|"can adapt sources"| node_external_data

click node_model "https://github.com/atk4/data/blob/develop/src/Model.php"
click node_field "https://github.com/atk4/data/blob/develop/src/Field.php"
click node_validation "https://github.com/atk4/data/blob/develop/src/Field/EmailField.php"
click node_relation "https://github.com/atk4/data/blob/develop/src/Reference.php"
click node_relation_kinds "https://github.com/atk4/data/blob/develop/src/Reference/HasMany.php"
click node_join "https://github.com/atk4/data/blob/develop/src/Model/Join.php"
click node_scope "https://github.com/atk4/data/blob/develop/src/Model/Scope.php"
click node_condition "https://github.com/atk4/data/blob/develop/src/Model/Scope/Condition.php"
click node_sql_field "https://github.com/atk4/data/blob/develop/src/Field/SqlExpressionField.php"
click node_expression "https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Expression.php"
click node_query_builder "https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Query.php"
click node_aggregate "https://github.com/atk4/data/blob/develop/src/Model/AggregateModel.php"
click node_persistence_base "https://github.com/atk4/data/blob/develop/src/Persistence.php"
click node_array_backend "https://github.com/atk4/data/blob/develop/src/Persistence/Array_.php"
click node_array_table "https://github.com/atk4/data/blob/develop/src/Persistence/Array_/Db/Table.php"
click node_array_actions "https://github.com/atk4/data/blob/develop/src/Persistence/Array_/Action.php"
click node_sql_backend "https://github.com/atk4/data/blob/develop/src/Persistence/Sql.php"
click node_sql_connection "https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Connection.php"
click node_sql_dialects "https://github.com/atk4/data/tree/develop/src/Persistence/Sql"
click node_csv "https://github.com/atk4/data/blob/develop/src/Persistence/Csv.php"
click node_static_backend "https://github.com/atk4/data/blob/develop/src/Persistence/Static_.php"
click node_migrator "https://github.com/atk4/data/blob/develop/src/Schema/Migrator.php"
click node_types "https://github.com/atk4/data/blob/develop/src/Type/Types.php"
click node_user_actions "https://github.com/atk4/data/blob/develop/src/Model/UserAction.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_model,node_field,node_validation,node_relation,node_relation_kinds,node_join,node_user_actions toneBlue
class node_scope,node_condition,node_sql_field,node_expression,node_query_builder,node_aggregate,node_sql_server,node_external_data toneAmber
class node_persistence_base,node_array_backend,node_array_table,node_array_actions,node_sql_backend,node_sql_connection,node_sql_dialects,node_csv,node_static_backend toneMint
class node_migrator,node_types toneRose
class node_ui,node_api,node_app toneIndigo
```

## Components

### Business modeling

- [Data model](https://github.com/atk4/data/blob/develop/src/Model.php): `src/Model.php`
- [Fields](https://github.com/atk4/data/blob/develop/src/Field.php): `src/Field.php`
- [Email field](https://github.com/atk4/data/blob/develop/src/Field/EmailField.php): `src/Field/EmailField.php`
- [Model relations](https://github.com/atk4/data/blob/develop/src/Reference.php): `src/Reference.php`
- [Relation types](https://github.com/atk4/data/blob/develop/src/Reference/HasMany.php): `src/Reference/HasMany.php`
- [Join configuration](https://github.com/atk4/data/blob/develop/src/Model/Join.php): `src/Model/Join.php`
- [User actions](https://github.com/atk4/data/blob/develop/src/Model/UserAction.php): `src/Model/UserAction.php`

### Query and expressions

- [Scopes and filters](https://github.com/atk4/data/blob/develop/src/Model/Scope.php): `src/Model/Scope.php`
- [Conditions](https://github.com/atk4/data/blob/develop/src/Model/Scope/Condition.php): `src/Model/Scope/Condition.php`
- [SQL expression fields](https://github.com/atk4/data/blob/develop/src/Field/SqlExpressionField.php): `src/Field/SqlExpressionField.php`
- [SQL expressions](https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Expression.php): `src/Persistence/Sql/Expression.php`
- [SQL query builder](https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Query.php): `src/Persistence/Sql/Query.php`
- [Aggregate models](https://github.com/atk4/data/blob/develop/src/Model/AggregateModel.php): `src/Model/AggregateModel.php`

### Persistence backends

- [Persistence contract](https://github.com/atk4/data/blob/develop/src/Persistence.php): `src/Persistence.php`
- [Array persistence](https://github.com/atk4/data/blob/develop/src/Persistence/Array_.php): `src/Persistence/Array_.php`
- [Array tables](https://github.com/atk4/data/blob/develop/src/Persistence/Array_/Db/Table.php): `src/Persistence/Array_/Db/Table.php`
- [Array actions](https://github.com/atk4/data/blob/develop/src/Persistence/Array_/Action.php): `src/Persistence/Array_/Action.php`
- [SQL persistence](https://github.com/atk4/data/blob/develop/src/Persistence/Sql.php): `src/Persistence/Sql.php`
- [SQL connection](https://github.com/atk4/data/blob/develop/src/Persistence/Sql/Connection.php): `src/Persistence/Sql/Connection.php`
- [SQL dialects](https://github.com/atk4/data/tree/develop/src/Persistence/Sql): `src/Persistence/Sql`
- [CSV persistence](https://github.com/atk4/data/blob/develop/src/Persistence/Csv.php): `src/Persistence/Csv.php`
- [Static persistence](https://github.com/atk4/data/blob/develop/src/Persistence/Static_.php): `src/Persistence/Static_.php`

### Schema and types

- [Schema migration](https://github.com/atk4/data/blob/develop/src/Schema/Migrator.php): `src/Schema/Migrator.php`
- [Type handling](https://github.com/atk4/data/blob/develop/src/Type/Types.php): `src/Type/Types.php`

### Application integration

- **Agile UI**
- **Agile API**

### Other components

- **Application code**
- **SQL database**
- **NoSQL or API source**

## Connections

- Application code → Data model: defines (evidence: `README.md`)
- Data model → Fields: adds fields (evidence: `src/Model.php`)
- Data model → Scopes and filters: builds scopes (evidence: `src/Model.php`)
- Scopes and filters → Conditions: contains conditions (evidence: `src/Model/Scope.php`)
- Data model → Model relations: defines relations (evidence: `src/Model.php`)
- Model relations → Relation types: uses relation types (evidence: `src/Reference.php`)
- Data model → Join configuration: configures joins (evidence: `src/Model.php`)
- Application code → Aggregate models: requests aggregates (evidence: `README.md`)
- Aggregate models → Data model: extends model behavior
- SQL expression fields → SQL expressions: builds expressions (evidence: `src/Field/SqlExpressionField.php`)
- Conditions → SQL expressions: accepts expressions (evidence: `src/Model/Scope/Condition.php`)
- Data model → Persistence contract: uses persistence (evidence: `src/Model.php`)
- Persistence contract → Type handling: typecasts fields (evidence: `src/Persistence.php`)
- Persistence contract → Array persistence: supports backends
- Array persistence → Array tables: stores rows (evidence: `src/Persistence/Array_/Db/Table.php`)
- Array persistence → Array actions: executes actions
- Persistence contract → SQL persistence: supports backends (evidence: `src/Persistence.php`)
- SQL persistence → SQL query builder: builds queries (evidence: `src/Persistence/Sql.php`)
- SQL persistence → SQL connection: uses connection (evidence: `src/Persistence/Sql.php`)
- SQL persistence → SQL expression fields: creates expression fields (evidence: `src/Persistence/Sql.php`)
- SQL query builder → SQL expressions: renders expressions (evidence: `src/Persistence/Sql/Query.php`)
- SQL connection → SQL database: connects to
- SQL persistence → SQL dialects: supports dialects (evidence: `src/Persistence/Sql.php`)
- Persistence contract → CSV persistence: supports backends
- Persistence contract → Static persistence: supports backends
- Application code → Schema migration: migrates schema
- Application code → User actions: defines actions
- Application code → Agile UI: binds model (evidence: `README.md`)
- Application code → Agile API: exposes endpoint (evidence: `README.md`)
- Persistence contract → NoSQL or API source: can adapt sources (evidence: `README.md`)
