How ratul701e/agentic-consensus works
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: app.module.ts App module · database.module.ts Database · transaction.module.ts Tx API · epoch.module.ts Epoch service
Components 25
Bootstrap & API
NestJS entrypoint, app wiring, controllers, DTOs, and request logging.
- main.ts · Application entrypoint.
src/main.ts - App module · Root module composing the application.
src/app.module.ts - Logger · 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 · Block-facing controller and service.
src/modules/block/block.module.ts - Blockchain API · Blockchain-facing controller and service.
src/modules/blockchain/blockchain.module.ts - Chain API · Chain progression and chain state operations.
src/modules/chain/chain.module.ts - Tx API · Transaction submission and handling.
src/modules/transaction/transaction.module.ts - VDF API · Verification delay/proof-related operations.
src/modules/vdf/vdf.module.ts - Epoch service · Epoch and slot lifecycle logic.
src/services/epoch/epoch.module.ts - Proof kit · Shared proof and verification utilities.
src/services/proof-kit/proof-kit.module.ts - 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 · Storage boundary and data access service.
src/modules/database/database.module.ts - Schemas · Persistent domain schemas for blockchain, tx, mempool, slot, epoch, and node info.
src/schemas/blockchain.schema.ts - Redis · Cache, pub/sub, or queue coordination layer.
src/services/redis-service/redis-service.module.ts - Events · 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 · Gateway and service for inbound peer traffic.
src/modules/p2p-server/p2p-server.module.ts - P2P client · 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 · Shared agent abstraction and provider-facing service.
src/services/agent/agent.module.ts - OpenAI agent · OpenAI-backed agent interface.
src/modules/openai-agent/openai-agent.module.ts - DeepSeek agent · DeepSeek-backed agent interface.
src/modules/deepseek-agent/deepseek-agent.module.ts - RAG · Retrieval-augmented generation subsystem with a Python sidecar.
src/modules/rag/rag.module.ts
Ops & Jobs
Diagnostics, test surface, and background processing.
- Info API · Node and runtime information surface.
src/modules/info/info.module.ts - Sys-info API · System and host metadata surface.
src/modules/sys-info/sys-info.module.ts - Test API · Auxiliary validation or test surface.
src/test/test.module.ts - Jobs · Queued or periodic processing, including performance analysis.
src/jobs/performance-analyzer.job.ts
Connections 34
- 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.