# idiolect-dev/idiolect architecture

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

- Interactive diagram: https://gitdiagram.com/idiolect-dev/idiolect
- Repository: https://github.com/idiolect-dev/idiolect

## Overview

Idiolect is a community-governed toolkit for defining, translating, verifying, and evolving shared data schemas. Its main workflow runs from authoring record definitions through change analysis and governance, to verified migration and signed release; published records can then be indexed and queried, while observers measure ecosystem activity. The graph also includes the identity and session layers used for publishing, plus generated Rust and TypeScript schema surfaces. README documents several subsystem links not visible in the sampled source, so those are shown only where the documentation explicitly describes them.

Main entry points: [`crates/idiolect-cli/src/main.rs`](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-cli/src/main.rs) (Idiolect CLI), [`crates/idiolect-community/src/lib.rs`](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-community/src/lib.rs) (Community workspace), [`crates/idiolect-indexer/src/indexer.rs`](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-indexer/src/indexer.rs) (Event indexer), [`crates/idiolect-lens/src/lib.rs`](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-lens/src/lib.rs) (Lens translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Schema authoring"]
  node_codegen["Schema codegen<br/>[lib.rs]"]
  node_records["Rust records<br/>[lib.rs]"]
  node_ts_schema["TypeScript schema<br/>[index.ts]"]
end

subgraph group_change["Change lifecycle"]
  node_community["Community workspace<br/>[lib.rs]"]
  node_lens["Lens translation<br/>[lib.rs]"]
  node_migrate["Migration planner<br/>[lib.rs]"]
  node_verify["Translation verifier<br/>[lib.rs]"]
end

subgraph group_runtime["Publishing runtime"]
  node_identity["Identity resolver<br/>[lib.rs]"]
  node_oauth["OAuth sessions<br/>[lib.rs]"]
end

subgraph group_discovery["Indexing and discovery"]
  node_indexer["Event indexer<br/>[indexer.rs]"]
  node_cursor_store[("Cursor store<br/>[cursor.rs]")]
  node_orchestrator["Query service<br/>[lib.rs]"]
  node_catalog[("Search catalog<br/>[catalog.rs]")]
  node_observer["Activity observer<br/>[lib.rs]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Idiolect CLI<br/>[main.rs]"]
end

node_community_user(("Community operator"))
node_app_client(("Application client"))
node_pds[("ATProto PDS and firehose")]

node_community_user -->|"operates"| node_cli
node_codegen -->|"generates types"| node_records
node_codegen -->|"generates validators"| node_ts_schema
node_community -->|"plans changes"| node_migrate
node_migrate -->|"translates records"| node_lens
node_community -->|"attaches evidence"| node_verify
node_community -->|"records approvals and releases"| node_community
node_identity -->|"resolves identities"| node_lens
node_oauth -->|"authenticates writes"| node_lens
node_lens -->|"publishes records"| node_pds
node_pds -->|"streams commits"| node_indexer
node_indexer -->|"persists progress"| node_cursor_store
node_indexer -->|"dispatches records"| node_orchestrator
node_orchestrator -->|"updates and queries"| node_catalog
node_indexer -->|"dispatches events"| node_observer
node_observer -->|"publishes observations"| node_pds
node_app_client -->|"queries catalog"| node_orchestrator
node_cli -->|"resolves DIDs"| node_identity
node_cli -->|"requests queries"| node_orchestrator
node_cli -->|"operates workspace"| node_community
node_cli -->|"runs checks"| node_verify

click node_community "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-community/src/lib.rs"
click node_codegen "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-codegen/src/lib.rs"
click node_records "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-records/src/lib.rs"
click node_ts_schema "https://github.com/idiolect-dev/idiolect/blob/main/packages/schema/src/index.ts"
click node_lens "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-lens/src/lib.rs"
click node_migrate "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-migrate/src/lib.rs"
click node_verify "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-verify/src/lib.rs"
click node_identity "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-identity/src/lib.rs"
click node_oauth "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-oauth/src/lib.rs"
click node_indexer "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-indexer/src/indexer.rs"
click node_cursor_store "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-indexer/src/cursor.rs"
click node_orchestrator "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-orchestrator/src/lib.rs"
click node_catalog "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-orchestrator/src/catalog.rs"
click node_observer "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-observer/src/lib.rs"
click node_cli "https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-cli/src/main.rs"

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_codegen,node_records,node_ts_schema,node_app_client toneBlue
class node_community,node_lens,node_migrate,node_verify,node_pds toneAmber
class node_identity,node_oauth toneMint
class node_indexer,node_cursor_store,node_orchestrator,node_catalog,node_observer toneRose
class node_cli,node_community_user toneIndigo
```

## Components

### Schema authoring

- [Schema codegen](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-codegen/src/lib.rs): `crates/idiolect-codegen/src/lib.rs`
- [Rust records](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-records/src/lib.rs): `crates/idiolect-records/src/lib.rs`
- [TypeScript schema](https://github.com/idiolect-dev/idiolect/blob/main/packages/schema/src/index.ts): `packages/schema/src/index.ts`

### Change lifecycle

- [Community workspace](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-community/src/lib.rs): `crates/idiolect-community/src/lib.rs`
- [Lens translation](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-lens/src/lib.rs): `crates/idiolect-lens/src/lib.rs`
- [Migration planner](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-migrate/src/lib.rs): `crates/idiolect-migrate/src/lib.rs`
- [Translation verifier](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-verify/src/lib.rs): `crates/idiolect-verify/src/lib.rs`

### Publishing runtime

- [Identity resolver](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-identity/src/lib.rs): `crates/idiolect-identity/src/lib.rs`
- [OAuth sessions](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-oauth/src/lib.rs): `crates/idiolect-oauth/src/lib.rs`

### Indexing and discovery

- [Event indexer](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-indexer/src/indexer.rs): `crates/idiolect-indexer/src/indexer.rs`
- [Cursor store](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-indexer/src/cursor.rs): `crates/idiolect-indexer/src/cursor.rs`
- [Query service](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-orchestrator/src/lib.rs): `crates/idiolect-orchestrator/src/lib.rs`
- [Search catalog](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-orchestrator/src/catalog.rs): `crates/idiolect-orchestrator/src/catalog.rs`
- [Activity observer](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-observer/src/lib.rs): `crates/idiolect-observer/src/lib.rs`

### User interfaces

- [Idiolect CLI](https://github.com/idiolect-dev/idiolect/blob/main/crates/idiolect-cli/src/main.rs): `crates/idiolect-cli/src/main.rs`

### Other components

- **Community operator**
- **Application client**
- **ATProto PDS and firehose**

## Connections

- Community operator → Idiolect CLI: operates
- Schema codegen → Rust records: generates types
- Schema codegen → TypeScript schema: generates validators
- Community workspace → Migration planner: plans changes
- Migration planner → Lens translation: translates records
- Community workspace → Translation verifier: attaches evidence
- Community workspace → Community workspace: records approvals and releases
- Identity resolver → Lens translation: resolves identities
- OAuth sessions → Lens translation: authenticates writes
- Lens translation → ATProto PDS and firehose: publishes records
- ATProto PDS and firehose → Event indexer: streams commits
- Event indexer → Cursor store: persists progress
- Event indexer → Query service: dispatches records
- Query service → Search catalog: updates and queries
- Event indexer → Activity observer: dispatches events
- Activity observer → ATProto PDS and firehose: publishes observations
- Application client → Query service: queries catalog
- Idiolect CLI → Identity resolver: resolves DIDs
- Idiolect CLI → Query service: requests queries
- Idiolect CLI → Community workspace: operates workspace
- Idiolect CLI → Translation verifier: runs checks