DEV Community

Darshit Khandelwal
Darshit Khandelwal

Posted on

Week - 1 (Phase 1)

#architecture #blockchain #devjournal #opensource

Week 1 of My LFDT Mentorship: Architecture, Hedera, and Getting Everything Running

Welcome to the first post of my LFDT (Linux Foundation Decentralized Trust) mentorship blog! Each week I'll be writing about what I built, what I learned, and — honestly — what confused me along the way.

Week 1 was all about planning, architecture decisions, and setting up the groundwork before any real code gets written. No flashy features yet, but a lot of important decisions that will shape everything that comes after. Let's get into it.

The Week at a Glance

Here's a quick summary of everything on my plate this week:

  • Align the implementation plan with my mentor and confirm the interpretation of Issue #87
  • Finalize the target architecture for the whole project
  • Sort out the Hedera testnet setup and operator credentials
  • Understand the revocation strategy and its scope during mentorship
  • Set up the local Heka development environment
  • Install and configure a GitHub App for local testing
  • Create a webhook fixture repository for replaying PR events
  • Prepare a PR slicing plan for incremental delivery

Aligning with the Mentor & Locking Down the Plan

The week started with a sync with my mentor to get the implementation plan nailed down. The good news is, the week-by-week plan has been finalized after a proper discussion, and the interpretation of Issue #87 has been confirmed. With the plan locked in, I can move forward with confidence in the coming weeks.

Deciding the Target Architecture

One of the bigger decisions this week was figuring out where everything actually lives, contributor onboarding, GitHub integration, credential issuance, DID management, and verification policy logic all need a home.

Here's what we landed on:

  • heka-identity-service — This is where the core modules live: contributor onboarding, credential issuance, DID management, and verification policy logic. All of this gets built as a dedicated module within this repo.
  • A separate GitHub repository — The GitHub integration code (the Probot app, webhook handling, check-run posting) lives in its own repo, completely separate from heka-identity-service. This keeps Heka clean and focused on identity, and makes the GitHub-specific code easier to extend or extract later.

There are still a few grey areas to iron out over the next couple of weeks, but the overall direction is clear and agreed upon.

Understanding Hedera: Consensus Nodes vs Mirror Nodes

If you're already familiar with Hedera's architecture, feel free to skip ahead to the next section!

Before I explain how Hedera fits into this project, let me share something I was confused about early on: what's the difference between a consensus node and a mirror node?

Unlike older blockchains (like Ethereum) that use a single node type for everything, Hedera splits the workload into two completely different node types to keep the network fast.

1. Consensus Node — The Write Database

  • This is where you send new transactions (like creating an account or logging a DID document to the ledger).
  • Its job is to receive the transaction, verify it, agree on a timestamp, and write it to the ledger as fast as possible.
  • Because it's hyper-focused on speed and new writes, it's not great at answering questions about old or historical data.

2. Mirror Node — The Read Database

  • The mirror node sits quietly alongside the consensus node and constantly copies (mirrors) every approved transaction.
  • Its only job is to take that raw blockchain data and organize it into a highly searchable traditional database (like PostgreSQL), and expose a REST API that developers can query.
  • Important caveat: you cannot send new transactions to the mirror node — it's strictly read-only.

How This Applies to Our Project

In practice, the two node types serve two completely different purposes in our system:

  • Writing (creating/updating a DID): Our backend uses the consensus node, authorized via operator credentials from our .env. The SDK signs the transaction automatically using the operator key.
  • Reading (showing transaction history or verifying an identity): The frontend makes a standard HTTP GET request directly to the mirror node's REST API — completely bypassing the consensus node.

Our .env will look something like this:

HEDERA_NETWORK=
OPERATOR_ID=
OPERATOR_KEY=
NODE_IP=
MIRROR_NODE_IP=
Enter fullscreen mode Exit fullscreen mode

HBAR Balance & Revocation Strategy

After clarifying with my mentor Alexander, I now have the credentials for the operator account. The account comes loaded with enough test HBAR tokens to cover everything I need during development — creating, updating, and querying DIDs. So the token balance won't be a blocker at all.

On the revocation front: implementing a full, hardened VC revocation mechanism is out of scope for this mentorship. The focus right now is on building a working prototype, so revocation will either be tackled in the second half of the mentorship or saved for post-mentorship work. For now, the expectation is lightweight documentation and runbook-level treatment — not a working mechanism.

Setting Up the Local Dev Environment

This was the most hands-on part of the week. Getting the local Heka environment running required wiring together three tools: Nginx, Ngrok, and a GitHub App. Let me walk through how they fit together.

The Nginx Routing Rules

Nginx listens on Port 8080 and applies two simple routing rules to every incoming request:

# Rule 1: Route GitHub Webhooks → Probot GitHub App (Port 3000)
location /api/webhook {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Rule 2: Route everything else → Heka Core Backend (Port 3001)
location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
Enter fullscreen mode Exit fullscreen mode

In plain English:

  1. If the request is to /api/webhook → forward it to the GitHub App on Port 3000
  2. Everything else → forward it to the main Heka backend on Port 3001

Why Ngrok Is Necessary

Here's the catch: Nginx only listens on localhost. But when GitHub fires a webhook event, "localhost" from GitHub's perspective means GitHub's own servers — not your machine. It would send the event into the void, find nothing, and drop it silently.

Ngrok solves this by creating a public tunnel from your local Port 8080 directly to the internet:

ngrok http 8080
Enter fullscreen mode Exit fullscreen mode

Ngrok gives you a temporary public URL — something like https://something.ngrok-free.app. You paste this into your GitHub App's webhook URL settings. Now the entire flow works end-to-end:

GitHub fires a PR event
        ↓
Hits the public Ngrok URL
        ↓
Ngrok tunnels it to Port 8080 on your local machine
        ↓
Nginx reads the request and applies the two routing rules
        ↓
Correct service handles it (Port 3000 or 3001)
Enter fullscreen mode Exit fullscreen mode

A one-liner to remember the whole pipeline:

GitHub labels it and sends it → Ngrok blindly transports it → Nginx reads it and diverts it.

Webhook Fixture Repository

To avoid opening real pull requests every single time I want to test webhook handling, I created a dedicated fixture repository for generating and replaying PR events during development.

You can find it here: darshit2308/Heka-Webhook-Fixture

The PR Slicing Plan

To keep development incremental and mentor-reviewable, I've planned out the PR delivery sequence. This is tentative for now, but here's the rough order:

  1. ADRs and credential profile documentation
  2. Deterministic DID verification method helper and Hedera secret validation
  3. GPG challenge lifecycle module with tests
  4. GitHub App adapter skeleton and check-run creation (separate repo from Heka, per mentor direction)
  5. GitHub OAuth and contributor binding
  6. Contributor credential OID4VCI support
  7. Heka Web Wallet prototype (lives inside the Heka repository; non-Askar key management)
  8. Heka Web UI onboarding flow
  9. Repository config parser and policy schema
  10. OID4VP verification integration (Web Wallet as the primary target)
  11. Lifecycle and recovery documentation (runbooks; no revocation implementation)
  12. E2E test suite, docs, and final demo artifacts

Looking Ahead

Week 1 was heavy on planning, decisions, and setup — but that's exactly how it should be. A solid foundation now means fewer surprises (and fewer painful rewrites) later. Starting next week, the real implementation begins: ADRs, the DID helper utilities, and the first PR going out the door.

Stay tuned for Week 2!

This post is part of my ongoing LFDT Mentorship 2026 blog series. Feel free to reach out if you have questions or want to discuss anything covered here!

Top comments (0)