# tablelandnetwork/go-tableland architecture

> Architecture diagram of the GitHub repository tablelandnetwork/go-tableland, 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/tablelandnetwork/go-tableland
- Repository: https://github.com/tablelandnetwork/go-tableland

## Overview

Tableland Validator materializes SQL mutations emitted by Tableland contracts on EVM chains and serves read queries over HTTP. The main workflow is: contract events are detected, validated and executed against SQLite; clients then query the materialized tables through the REST API. The repository also includes client-side contract operations, backups and telemetry. Connections for event ingestion and API assembly are based on README descriptions and the sampled entry point; unsampled implementation details are not expanded.

Main entry points: [`cmd/api/main.go`](https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/api/main.go) (Validator process), [`pkg/eventprocessor/impl/executor/impl`](https://github.com/tablelandnetwork/go-tableland/tree/main/pkg/eventprocessor/impl/executor/impl) (Transaction executor), [`internal/gateway/gateway.go`](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/gateway/gateway.go) (Query gateway), [`pkg/eventprocessor/impl/eventprocessor.go`](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/eventprocessor/impl/eventprocessor.go) (Event processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Chain ingestion"]
  node_event_feed["Event feed<br/>[eventfeed.go]"]
  node_event_processor["Event processor<br/>[eventprocessor.go]"]
end

subgraph group_execution["SQL execution"]
  node_executor["Transaction executor"]
  node_sql_validator["SQL validator<br/>[validator.go]"]
  node_acl["Access control<br/>[acl.go]"]
  node_sqlite[("SQLite database<br/>[sqlite_db.go]")]
end

subgraph group_api["Read API"]
  node_router["HTTP router<br/>[router.go]"]
  node_controller["API controller<br/>[controller.go]"]
  node_gateway["Query gateway<br/>[gateway.go]"]
  node_gateway_store["Gateway store<br/>[gateway_store.go]"]
end

subgraph group_operations["Operations and observability"]
  node_api_process["Validator process<br/>[main.go]"]
  node_backup["Backup service<br/>[backuper.go]"]
  node_telemetry_store[("Telemetry storage<br/>[db.go]")]
  node_metrics_hub["Metrics hub<br/>[main.go]"]
end

subgraph group_client["Client tooling"]
  node_client_lib["Go client<br/>[client.go]"]
  node_ethereum_client["Contract client<br/>[client.go]"]
  node_healthbot["Health bot<br/>[main.go]"]
end

node_operator(("Node operator"))
node_user(("Application user"))
node_evm["EVM chain"]

node_operator -->|"runs node"| node_api_process
node_user -->|"submits mutations"| node_evm
node_evm -->|"emits events"| node_event_feed
node_event_feed -.->|"delivers events"| node_event_processor
node_event_processor -.->|"dispatches events"| node_executor
node_executor -.->|"validates SQL"| node_sql_validator
node_executor -.->|"checks permissions"| node_acl
node_executor -->|"executes mutations"| node_sqlite
node_user -->|"sends query"| node_router
node_router -->|"routes requests"| node_controller
node_controller -->|"runs query"| node_gateway
node_gateway -->|"validates reads"| node_sql_validator
node_gateway -.->|"delegates storage"| node_gateway_store
node_gateway_store -.->|"reads tables"| node_sqlite
node_api_process -->|"starts processor"| node_event_processor
node_api_process -->|"starts HTTP API"| node_router
node_api_process -->|"starts backups"| node_backup
node_api_process -.->|"sets up telemetry"| node_telemetry_store
node_metrics_hub -.->|"stores metrics"| node_telemetry_store
node_user -.->|"uses client"| node_client_lib
node_client_lib -->|"submits transactions"| node_ethereum_client
node_ethereum_client -.->|"calls contract"| node_evm
node_operator -.->|"runs probe"| node_healthbot
node_healthbot -->|"creates client"| node_client_lib

click node_api_process "https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/api/main.go"
click node_event_feed "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/eventprocessor/eventfeed/impl/eventfeed.go"
click node_event_processor "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/eventprocessor/impl/eventprocessor.go"
click node_executor "https://github.com/tablelandnetwork/go-tableland/tree/main/pkg/eventprocessor/impl/executor/impl"
click node_sql_validator "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/parsing/impl/validator.go"
click node_acl "https://github.com/tablelandnetwork/go-tableland/blob/main/internal/tableland/acl.go"
click node_sqlite "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/database/sqlite_db.go"
click node_router "https://github.com/tablelandnetwork/go-tableland/blob/main/internal/router/router.go"
click node_controller "https://github.com/tablelandnetwork/go-tableland/blob/main/internal/router/controllers/controller.go"
click node_gateway "https://github.com/tablelandnetwork/go-tableland/blob/main/internal/gateway/gateway.go"
click node_gateway_store "https://github.com/tablelandnetwork/go-tableland/blob/main/internal/gateway/impl/gateway_store.go"
click node_backup "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/backup/backuper.go"
click node_telemetry_store "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/telemetry/storage/db.go"
click node_metrics_hub "https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/metricshub/main.go"
click node_client_lib "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/client/v1/client.go"
click node_ethereum_client "https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/tables/impl/ethereum/client.go"
click node_healthbot "https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/healthbot/main.go"

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_event_feed,node_event_processor,node_user toneBlue
class node_executor,node_sql_validator,node_acl,node_sqlite toneAmber
class node_router,node_controller,node_gateway,node_gateway_store toneMint
class node_api_process,node_backup,node_telemetry_store,node_metrics_hub toneRose
class node_client_lib,node_ethereum_client,node_healthbot,node_operator,node_evm toneIndigo
```

## Components

### Chain ingestion

- [Event feed](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/eventprocessor/eventfeed/impl/eventfeed.go): `pkg/eventprocessor/eventfeed/impl/eventfeed.go`
- [Event processor](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/eventprocessor/impl/eventprocessor.go): `pkg/eventprocessor/impl/eventprocessor.go`

### SQL execution

- [Transaction executor](https://github.com/tablelandnetwork/go-tableland/tree/main/pkg/eventprocessor/impl/executor/impl): `pkg/eventprocessor/impl/executor/impl`
- [SQL validator](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/parsing/impl/validator.go): `pkg/parsing/impl/validator.go`
- [Access control](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/tableland/acl.go): `internal/tableland/acl.go`
- [SQLite database](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/database/sqlite_db.go): `pkg/database/sqlite_db.go`

### Read API

- [HTTP router](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/router/router.go): `internal/router/router.go`
- [API controller](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/router/controllers/controller.go): `internal/router/controllers/controller.go`
- [Query gateway](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`
- [Gateway store](https://github.com/tablelandnetwork/go-tableland/blob/main/internal/gateway/impl/gateway_store.go): `internal/gateway/impl/gateway_store.go`

### Operations and observability

- [Validator process](https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Backup service](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/backup/backuper.go): `pkg/backup/backuper.go`
- [Telemetry storage](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/telemetry/storage/db.go): `pkg/telemetry/storage/db.go`
- [Metrics hub](https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/metricshub/main.go): `cmd/metricshub/main.go`

### Client tooling

- [Go client](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/client/v1/client.go): `pkg/client/v1/client.go`
- [Contract client](https://github.com/tablelandnetwork/go-tableland/blob/main/pkg/tables/impl/ethereum/client.go): `pkg/tables/impl/ethereum/client.go`
- [Health bot](https://github.com/tablelandnetwork/go-tableland/blob/main/cmd/healthbot/main.go): `cmd/healthbot/main.go`

### Other components

- **Node operator**
- **Application user**
- **EVM chain**

## Connections

- Node operator → Validator process: runs node (evidence: `README.md`)
- Application user → EVM chain: submits mutations (evidence: `README.md`)
- EVM chain → Event feed: emits events (evidence: `README.md`)
- Event feed → Event processor: delivers events
- Event processor → Transaction executor: dispatches events
- Transaction executor → SQL validator: validates SQL
- Transaction executor → Access control: checks permissions
- Transaction executor → SQLite database: executes mutations (evidence: `README.md`)
- Application user → HTTP router: sends query (evidence: `README.md`)
- HTTP router → API controller: routes requests (evidence: `internal/router/router.go`)
- API controller → Query gateway: runs query (evidence: `internal/router/controllers/controller.go`)
- Query gateway → SQL validator: validates reads (evidence: `internal/gateway/gateway.go`)
- Query gateway → Gateway store: delegates storage
- Gateway store → SQLite database: reads tables
- Validator process → Event processor: starts processor (evidence: `cmd/api/main.go`)
- Validator process → HTTP router: starts HTTP API (evidence: `cmd/api/main.go`)
- Validator process → Backup service: starts backups (evidence: `cmd/api/main.go`)
- Validator process → Telemetry storage: sets up telemetry
- Metrics hub → Telemetry storage: stores metrics
- Application user → Go client: uses client
- Go client → Contract client: submits transactions
- Contract client → EVM chain: calls contract
- Node operator → Health bot: runs probe
- Health bot → Go client: creates client (evidence: `cmd/healthbot/main.go`)
