# ratul701e/agentic-consensus architecture

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

- Interactive diagram: https://gitdiagram.com/ratul701e/agentic-consensus
- Repository: https://github.com/ratul701e/agentic-consensus

## Overview

1. **Overall shape**
   - This is a **single NestJS TypeScript backend** organized as a modular monolith.
   - `main.ts` bootstraps the app; `app.module.ts` wires the feature modules together.
   - `custom.logger.ts` and `logger.middleware.ts` indicate centralized request/log handling at the HTTP boundary.

2. **Primary domain: blockchain node/runtime**
   - The core business logic lives in `block`, `blockchain`, `chain`, `transaction`, `vdf`, and `epoch`.
   - These modules likely model the node’s internal state machine: blocks, transactions, chain progression, epochs/slots, and proof/verification steps.
   - `schemas/` contains persistent domain models such as `blockchain`, `transaction`, `mempool`, `slot`, `epoch`, and `node-info`.

3. **Request/API layer**
   - Most user-facing functionality is exposed through Nest **controllers** paired with **services**.
   - `dtos/` and module-local DTO files define input/output contracts for block, transaction, mempool, and chain operations.
   - The `info`, `sys-info`, and `test` modules look like auxiliary API surfaces for status, diagnostics, and validation.

4. **Core data flow**
   - API requests enter controllers, are validated/normalized via DTOs, then delegated to domain services.
   - Those services interact with the persistence layer (`database` module and `schemas`), emit internal events, or trigger background/peer/network actions.
   - The architecture suggests state is not kept in controllers; controllers are thin, services own behavior.

5. **Persistence boundary**
   - `modules/database` and the domain schemas form the storage boundary.
   - The schema-based structure suggests an ODM-style persistence model, with domain entities kept separate from transport DTOs.
   - `redis-service` is a distinct infrastructure dependency, likely used for caching, coordination, pub/sub, or queue-backed workflows.

6. **Peer-to-peer networking**
   - `p2p-server` and `p2p-client` are separate modules with gateway-style classes, so node-to-node communication is a first-class subsystem.
   - This is the main boundary between local node state and the wider network: one side serves peer connections, the other initiates or consumes peer traffic.
   - `internal-event-emitter` likely decouples network events from core chain/block logic.

7. **Async/background processing**
   - `jobs/performance-analyzer.job.ts` plus `queue.enum.ts` show there is background or queued processing in addition to synchronous request handling.
   - `epoch` services/modules and the job system likely support periodic chain metrics, slot/epoch transitions, or operational analysis.
   - Redis is a plausible coordination layer for these jobs.

8. **AI/agent subsystem**
   - `openai-agent`, `deepseek-agent`, and the shared `services/agent` module form an AI integration boundary.
   - `Class/LLM.ts` suggests a provider abstraction for language-model calls.
   - These modules are separated from blockchain logic, indicating LLM-driven features are optional adjunct capabilities rather than core consensus logic.

9. **RAG integration**
   - `modules/rag` is a dedicated retrieval-augmented generation subsystem.
   - The presence of `rag.py` alongside `rag.service.ts` shows a **cross-language boundary**: NestJS orchestrates the feature, while Python likely handles part of the retrieval or embedding workflow.
   - This module probably serves the agent layer by supplying context or search results.

10. **Cryptographic/proof-related support**
   - `services/proof-kit` and the `vdf` module point to proof generation/verification concerns.
   - These are likely supporting services for chain validation or verification workflows rather than standalone user features.
   - `programs/transferDclToken.program.ts` suggests some domain-specific execution/program abstraction for token transfer logic.

11. **Operational visibility**
   - `info` and `sys-info` expose runtime or node metadata, likely including process, host, or chain status.
   - `modules/database` plus `schemas/node-info.schema.ts` suggest the system persists some node-level telemetry or registration data.
   - This makes observability part of the application architecture, not just logging.

12. **Tooling and delivery**
   - The repo is set up with standard NestJS tooling: Jest e2e tests, ESLint, Prettier, and Nest CLI.
   - The presence of both `package-lock.json` and `pnpm-lock.yaml` indicates Node package management support is in place, but the architecture itself is framework-driven rather than build-tool-specific.

**In diagram terms:** the system is best drawn as a NestJS modular backend centered on blockchain state management, with side boundaries for peer networking, persistence/cache, async jobs, AI/RAG integrations, and proof/crypto utilities.

Main entry points: [`src/app.module.ts`](https://github.com/ratul701e/agentic-consensus/blob/development/src/app.module.ts) (App module), [`src/modules/database/database.module.ts`](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/database/database.module.ts) (Database), [`src/modules/transaction/transaction.module.ts`](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/transaction/transaction.module.ts) (Tx API), [`src/services/epoch/epoch.module.ts`](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/epoch/epoch.module.ts) (Epoch service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Bootstrap & API"]
  node_main["main.ts<br/>bootstrap<br/>[main.ts]"]
  node_appmodule["App module<br/>wiring<br/>[app.module.ts]"]
  node_logger["Logger<br/>http logging<br/>[custom.logger.ts]"]
end

subgraph group_g2["Consensus Core"]
  node_block["Block API<br/>[block.module.ts]"]
  node_blockchain["Blockchain API"]
  node_chain["Chain API<br/>[chain.module.ts]"]
  node_transaction["Tx API"]
  node_vdf["VDF API<br/>[vdf.module.ts]"]
  node_epoch["Epoch service<br/>[epoch.module.ts]"]
  node_proof{{"Proof kit<br/>crypto support"}}
  node_programs["Programs"]
end

subgraph group_g3["Persistence & Runtime"]
  node_database[("Database<br/>persistence<br/>[database.module.ts]")]
  node_schemas["Schemas<br/>models"]
  node_redis[("Redis<br/>coordination")]
  node_events(("Events<br/>internal bus"))
end

subgraph group_g4["Peer Network"]
  node_p2pserver["P2P server<br/>peer ingress"]
  node_p2pclient["P2P client<br/>peer egress"]
end

subgraph group_g5["AI & RAG"]
  node_agent["Agent core<br/>llm orchestration<br/>[agent.module.ts]"]
  node_openai["OpenAI agent<br/>llm module"]
  node_deepseek["DeepSeek agent<br/>llm module"]
  node_rag["RAG<br/>retrieval<br/>[rag.module.ts]"]
end

subgraph group_g6["Ops & Jobs"]
  node_info["Info API<br/>diagnostics<br/>[info.module.ts]"]
  node_sysinfo["Sys-info API<br/>observability<br/>[sys-info.module.ts]"]
  node_test["Test API<br/>auxiliary<br/>[test.module.ts]"]
  node_jobs["Jobs<br/>background"]
end

node_main -->|"bootstraps"| node_appmodule
node_appmodule -->|"middleware"| node_logger
node_appmodule -->|"loads"| node_block
node_appmodule -->|"loads"| node_blockchain
node_appmodule -->|"loads"| node_chain
node_appmodule -->|"loads"| node_transaction
node_appmodule -->|"loads"| node_vdf
node_appmodule -->|"loads"| node_epoch
node_appmodule -->|"loads"| node_p2pserver
node_appmodule -->|"loads"| node_p2pclient
node_appmodule -->|"loads"| node_agent
node_appmodule -->|"loads"| node_rag
node_appmodule -->|"loads"| node_info
node_appmodule -->|"loads"| node_sysinfo
node_appmodule -->|"loads"| node_test
node_block -->|"reads/writes"| node_database
node_blockchain -->|"reads/writes"| node_database
node_chain -->|"advances"| node_epoch
node_transaction -->|"reads/writes"| node_database
node_transaction -.->|"publishes"| node_events
node_vdf -->|"uses"| node_proof
node_epoch -.->|"coordinates"| node_redis
node_jobs -.->|"runs via"| node_redis
node_jobs -.->|"analyzes"| node_epoch
node_p2pserver -->|"emits"| node_events
node_p2pclient -->|"consumes"| node_events
node_p2pserver -->|"syncs"| node_blockchain
node_agent -->|"retrieves context"| node_rag
node_openai -->|"implements"| node_agent
node_deepseek -->|"implements"| node_agent
node_info -->|"reads"| node_database
node_sysinfo -->|"reads"| node_database
node_programs -.->|"executes"| node_transaction
node_schemas -->|"defines models"| node_database

click node_main "https://github.com/ratul701e/agentic-consensus/blob/development/src/main.ts"
click node_appmodule "https://github.com/ratul701e/agentic-consensus/blob/development/src/app.module.ts"
click node_logger "https://github.com/ratul701e/agentic-consensus/blob/development/src/logger/custom.logger.ts"
click node_block "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/block/block.module.ts"
click node_blockchain "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/blockchain/blockchain.module.ts"
click node_chain "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/chain/chain.module.ts"
click node_transaction "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/transaction/transaction.module.ts"
click node_vdf "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/vdf/vdf.module.ts"
click node_epoch "https://github.com/ratul701e/agentic-consensus/blob/development/src/services/epoch/epoch.module.ts"
click node_database "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/database/database.module.ts"
click node_schemas "https://github.com/ratul701e/agentic-consensus/blob/development/src/schemas/blockchain.schema.ts"
click node_redis "https://github.com/ratul701e/agentic-consensus/blob/development/src/services/redis-service/redis-service.module.ts"
click node_events "https://github.com/ratul701e/agentic-consensus/blob/development/src/services/internal-event-emitter/internal-event-emitter.module.ts"
click node_p2pserver "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/p2p-server/p2p-server.module.ts"
click node_p2pclient "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/p2p-client/p2p-client.module.ts"
click node_agent "https://github.com/ratul701e/agentic-consensus/blob/development/src/services/agent/agent.module.ts"
click node_openai "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/openai-agent/openai-agent.module.ts"
click node_deepseek "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/deepseek-agent/deepseek-agent.module.ts"
click node_rag "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/rag/rag.module.ts"
click node_info "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/info/info.module.ts"
click node_sysinfo "https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/sys-info/sys-info.module.ts"
click node_test "https://github.com/ratul701e/agentic-consensus/blob/development/src/test/test.module.ts"
click node_jobs "https://github.com/ratul701e/agentic-consensus/blob/development/src/jobs/performance-analyzer.job.ts"
click node_proof "https://github.com/ratul701e/agentic-consensus/blob/development/src/services/proof-kit/proof-kit.module.ts"
click node_programs "https://github.com/ratul701e/agentic-consensus/blob/development/src/programs/transferDclToken.program.ts"

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_main,node_appmodule,node_logger toneBlue
class node_block,node_blockchain,node_chain,node_transaction,node_vdf,node_epoch,node_proof,node_programs toneAmber
class node_database,node_schemas,node_redis,node_events toneMint
class node_p2pserver,node_p2pclient toneRose
class node_agent,node_openai,node_deepseek,node_rag toneIndigo
class node_info,node_sysinfo,node_test,node_jobs toneTeal
```

## Components

### Bootstrap & API

NestJS entrypoint, app wiring, controllers, DTOs, and request logging.

- [main.ts](https://github.com/ratul701e/agentic-consensus/blob/development/src/main.ts): bootstrap · Application entrypoint. · `src/main.ts`
- [App module](https://github.com/ratul701e/agentic-consensus/blob/development/src/app.module.ts): wiring · Root module composing the application. · `src/app.module.ts`
- [Logger](https://github.com/ratul701e/agentic-consensus/blob/development/src/logger/custom.logger.ts): http logging · Custom logger and HTTP middleware for request logging. · `src/logger/custom.logger.ts`

### Consensus Core

Blockchain state, chain progression, blocks, transactions, epochs, and VDF/proof logic.

- [Block API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/block/block.module.ts): module · Block-facing controller and service. · `src/modules/block/block.module.ts`
- [Blockchain API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/blockchain/blockchain.module.ts): module · Blockchain-facing controller and service. · `src/modules/blockchain/blockchain.module.ts`
- [Chain API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/chain/chain.module.ts): module · Chain progression and chain state operations. · `src/modules/chain/chain.module.ts`
- [Tx API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/transaction/transaction.module.ts): module · Transaction submission and handling. · `src/modules/transaction/transaction.module.ts`
- [VDF API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/vdf/vdf.module.ts): module · Verification delay/proof-related operations. · `src/modules/vdf/vdf.module.ts`
- [Epoch service](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/epoch/epoch.module.ts): service · Epoch and slot lifecycle logic. · `src/services/epoch/epoch.module.ts`
- [Proof kit](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/proof-kit/proof-kit.module.ts): crypto support · Shared proof and verification utilities. · `src/services/proof-kit/proof-kit.module.ts`
- [Programs](https://github.com/ratul701e/agentic-consensus/blob/development/src/programs/transferDclToken.program.ts): domain programs · Domain-specific execution/program abstractions such as token transfer. · `src/programs/transferDclToken.program.ts`

### Persistence & Runtime

Database, schemas, Redis coordination, and internal events.

- [Database](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/database/database.module.ts): persistence · Storage boundary and data access service. · `src/modules/database/database.module.ts`
- [Schemas](https://github.com/ratul701e/agentic-consensus/blob/development/src/schemas/blockchain.schema.ts): models · Persistent domain schemas for blockchain, tx, mempool, slot, epoch, and node info. · `src/schemas/blockchain.schema.ts`
- [Redis](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/redis-service/redis-service.module.ts): coordination · Cache, pub/sub, or queue coordination layer. · `src/services/redis-service/redis-service.module.ts`
- [Events](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/internal-event-emitter/internal-event-emitter.module.ts): internal bus · Internal event emitter used to decouple subsystems. · `src/services/internal-event-emitter/internal-event-emitter.module.ts`

### Peer Network

Inbound and outbound peer-to-peer communication layers.

- [P2P server](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/p2p-server/p2p-server.module.ts): peer ingress · Gateway and service for inbound peer traffic. · `src/modules/p2p-server/p2p-server.module.ts`
- [P2P client](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/p2p-client/p2p-client.module.ts): peer egress · Gateway and service for outbound peer communication. · `src/modules/p2p-client/p2p-client.module.ts`

### AI & RAG

LLM agents and retrieval-augmented generation integration.

- [Agent core](https://github.com/ratul701e/agentic-consensus/blob/development/src/services/agent/agent.module.ts): llm orchestration · Shared agent abstraction and provider-facing service. · `src/services/agent/agent.module.ts`
- [OpenAI agent](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/openai-agent/openai-agent.module.ts): llm module · OpenAI-backed agent interface. · `src/modules/openai-agent/openai-agent.module.ts`
- [DeepSeek agent](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/deepseek-agent/deepseek-agent.module.ts): llm module · DeepSeek-backed agent interface. · `src/modules/deepseek-agent/deepseek-agent.module.ts`
- [RAG](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/rag/rag.module.ts): retrieval · Retrieval-augmented generation subsystem with a Python sidecar. · `src/modules/rag/rag.module.ts`

### Ops & Jobs

Diagnostics, test surface, and background processing.

- [Info API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/info/info.module.ts): diagnostics · Node and runtime information surface. · `src/modules/info/info.module.ts`
- [Sys-info API](https://github.com/ratul701e/agentic-consensus/blob/development/src/modules/sys-info/sys-info.module.ts): observability · System and host metadata surface. · `src/modules/sys-info/sys-info.module.ts`
- [Test API](https://github.com/ratul701e/agentic-consensus/blob/development/src/test/test.module.ts): auxiliary · Auxiliary validation or test surface. · `src/test/test.module.ts`
- [Jobs](https://github.com/ratul701e/agentic-consensus/blob/development/src/jobs/performance-analyzer.job.ts): background · Queued or periodic processing, including performance analysis. · `src/jobs/performance-analyzer.job.ts`

## Connections

- main.ts → App module: bootstraps · Application starts here and loads the root module.
- App module → Logger: middleware · HTTP request logging is attached at the application boundary.
- App module → Block API: loads · Root module composes the block feature.
- App module → Blockchain API: loads · Root module composes blockchain operations.
- App module → Chain API: loads · Root module composes chain operations.
- App module → Tx API: loads · Root module composes transaction handling.
- App module → VDF API: loads · Root module composes VDF/proof operations.
- App module → Epoch service: loads · Root module composes epoch lifecycle services.
- App module → P2P server: loads · Peer server is part of the application runtime.
- App module → P2P client: loads · Peer client is part of the application runtime.
- App module → Agent core: loads · Shared agent orchestration is wired into the app.
- App module → RAG: loads · RAG subsystem is wired into the app.
- App module → Info API: loads · Diagnostics API is exposed by the app.
- App module → Sys-info API: loads · System info API is exposed by the app.
- App module → Test API: loads · Auxiliary test surface is exposed by the app.
- Block API → Database: reads/writes · Block operations persist and load state through the database boundary.
- Blockchain API → Database: reads/writes · Blockchain state is persisted through the database layer.
- Chain API → Epoch service: advances · Chain logic depends on epoch and slot progression.
- Tx API → Database: reads/writes · Transactions are stored and retrieved via persistence.
- Tx API → Events: publishes · Transaction activity is broadcast to internal consumers.
- VDF API → Proof kit: uses · VDF functionality relies on shared proof utilities.
- Epoch service → Redis: coordinates · Epoch processing can use Redis for coordination or queue-backed workflows.
- Jobs → Redis: runs via · Background jobs likely use Redis for scheduling or orchestration.
- Jobs → Epoch service: analyzes · Performance analysis is tied to epoch and slot behavior.
- P2P server → Events: emits · Inbound peer messages are decoupled from core logic via events.
- P2P client → Events: consumes · Outbound peer activity is coordinated through internal events.
- P2P server → Blockchain API: syncs · Peer traffic exchanges blockchain state and updates.
- Agent core → RAG: retrieves context · Agents can use retrieval to ground LLM responses.
- OpenAI agent → Agent core: implements · OpenAI module is one provider-facing agent implementation.
- DeepSeek agent → Agent core: implements · DeepSeek module is another provider-facing agent implementation.
- Info API → Database: reads · Node info and runtime metadata can be persisted or queried.
- Sys-info API → Database: reads · System information may be backed by persisted node metadata.
- Programs → Tx API: executes · Program abstractions relate to transaction execution paths.
- Schemas → Database: defines models · Domain schemas underpin the persistence boundary.