A distributed, event‑sourced audit platform built on CQRS, Event Sourcing, Reactive microservices, and Blockchain anchoring. The system provides an immutable audit trail with on‑chain integrity verification.
- CQRS + Event Sourcing architecture
- Immutable audit log stored in PostgreSQL
- Blockchain anchoring via Solidity smart contract
- Reactive stack: Spring WebFlux + R2DBC
- Kafka‑based event backbone
- Angular UI for audit exploration
- Integrity check API (DB hash vs blockchain hash)
- Full CI/CD pipeline (backend + frontend + blockchain + SonarQube)
@startuml
left to right direction
rectangle "Client" as Client
rectangle "command-service\n8081" as CommandService
queue "Kafka\ntopic user.login.events" as Kafka
rectangle "event-store-service\n8082" as EventStore
rectangle "audit-writer-service\n8083" as AuditWriter
database "PostgreSQL\naudit.events" as Postgres
rectangle "Ganache\nAuditLedger" as Blockchain
rectangle "query-service\n8084" as QueryService
Client --> CommandService : POST /commands/user/login
CommandService --> Kafka : publish event
Kafka --> EventStore : event-store-consumer
Kafka --> AuditWriter : audit-writer-consumer
EventStore --> Postgres : persist payload and event_hash
AuditWriter --> Blockchain : appendAuditRecord
Client --> QueryService : GET /api/audit-logs
Postgres --> QueryService : read models
Blockchain --> QueryService : integrity verification
@endumlFull architecture details are available in docs/ARCHITECTURE.md and docs/CQRS_FLOW.md.
- Docker Desktop
- Java 25+
- Node.js 20+
- Maven 3.9+
cd deploy
cp .env.example .env
docker compose up -dVerify infrastructure is ready:
- Postgres:
localhost:5432(accessible via pgAdmin atlocalhost:5050) - Kafka:
localhost:9092 - Ganache:
localhost:8545
cd ../blockchain
npm install
cp .env.example .env
# Set GANACHE_PRIVATE_KEY in .env (0x-prefixed 32-byte hex string, e.g. 0x...64 hex chars)
npm run deploy:ganacheAfter npm run deploy:ganache, copy the deployed contract address and set backend env vars.
export AUDIT_LEDGER_CONTRACT_ADDRESS=<deployed_contract_address>
export GANACHE_PRIVATE_KEY=0x<64_hex_chars>
export AUDIT_LEDGER_CONTRACT_DEPLOYMENT_BLOCK=0For PowerShell:
$env:AUDIT_LEDGER_CONTRACT_ADDRESS = "<deployed_contract_address>"
$env:GANACHE_PRIVATE_KEY = "0x<64_hex_chars>"
$env:AUDIT_LEDGER_CONTRACT_DEPLOYMENT_BLOCK = "0"cd ../backend
# Build and run tests
mvn clean verifyOptional troubleshooting on clean environments (if local Maven cache is missing shared modules):
mvn clean install -pl common/event-model,common/shared-contracts -DskipTestsStart services in separate terminals (from backend/):
cd ../backend
mvn spring-boot:run -pl command-service -am
mvn spring-boot:run -pl event-store-service -am
mvn spring-boot:run -pl audit-writer-service -am
mvn spring-boot:run -pl query-service -amService ports:
- Command Service:
8081 - Event Store Service:
8082 - Audit Writer Service:
8083 - Query Service:
8084
cd frontend/audit-ui
npm install
npm startOpen http://localhost:4200 — proxies to query-service on 8084
Detailed deployment instructions: docs/DEPLOYMENT.md
- Client sends a command to Command Service (
POST /commands/user/login) - Command Service publishes an event to Kafka topic
- Event Store Service (consumer) persists the event to PostgreSQL with SHA-256 hash
- Audit Writer Service (consumer) anchors the event hash on-chain via
AuditLedger.appendAuditRecord() - Query Service exposes read models with integrity check status
ON_CHAIN— event hash verified on blockchainMISMATCH— event exists in DB but not on-chain (indicates a failure)PENDING— event not yet processed by Audit Writer
See the detailed flow: docs/CQRS_FLOW.md
| Folder | Purpose |
|---|---|
backend/ |
Reactive microservices (CQRS + Event Sourcing, Spring WebFlux + R2DBC) |
blockchain/ |
Solidity smart contract (Hardhat) + tests |
frontend/audit-ui/ |
Angular 17+ UI dashboard |
deploy/ |
Docker Compose, local infrastructure configs |
docs/ |
Architecture, CQRS flow, deployment, testing, roadmap |
See START_HERE.md for guided navigation.
- #1–#2 — Repository setup + Docker Compose infrastructure
- #3 — Solidity smart contract
AuditLedgerwith Hardhat - #4–#8 — Backend services: Command, Event Store, Audit Writer, Query
- #9 — Integrity check endpoint (DB vs blockchain hash verification)
- #10–#11 — Angular UI with API integration
- #12 — Architecture documentation
- #13 — CI/CD pipeline (GitHub Actions + SonarQube + Telegram notifications)
- #14 — Support additional event types (
UserProfileChanged,EntityCreated,EntityUpdated,DataDeleted) - #15 — Authentication & Authorization (JWT + Spring Security + RBAC)
- #16 — Advanced filtering, search, date range picker, CSV export
- #17 — Event timeline visualization
- #18 — Reconciliation Service (batch integrity checking + Quartz scheduler)
- #19 — Kubernetes manifests + Helm chart
- #20 — Live demo scenario + Q&A documentation
Full roadmap and issue tracking: docs/ROADMAP.md
Follow the contribution guidelines:
- Branch naming:
<type>/#XX-descriptionwheretype=feature|fix|docs|test - Commits:
[#XX] Short description - PR description: Must include
Closes #XX(links to the issue) - One feature per issue — see docs/ROADMAP.md for issue list
- Testing: Run
mvn clean verifybefore submitting
Detailed guidelines: CONTRIBUTING.md
All documentation is located in the docs/ directory:
| Document | Purpose |
|---|---|
| START_HERE.md | 👈 Start here — guided navigation for developers |
| docs/ARCHITECTURE.md | System architecture, service boundaries, data flow |
| docs/CQRS_FLOW.md | Detailed CQRS + Event Sourcing runtime flow |
| docs/DEPLOYMENT.md | Quickstart + environment setup |
| docs/ROADMAP.md | Complete GitHub Issues roadmap (Phase 1–4) |
| docs/TESTING_SCENARIOS.md | Live demo scenarios + curl commands + screenshots |
| docs/LIVE_DEMO_QA.md | Interview-ready live demo script + architecture Q&A |
| docs/EVENT_HASH_CANONICAL_MIGRATION.md | Event hash canonicalization + recovery procedures |
| CONTRIBUTING.md | Contribution workflow, PR guidelines |
MIT License