Architecture Note · Context Retrieval Layer

How idfc-coder Actually Sees the Codebase
The Role of Helium

A focused look at one question: when idfc-coder generates code for a Jira ticket, where does it actually get its understanding of the codebase from — and, since documenting every database field was a stated requirement, how does that documentation reach the LLM too?

Knowledge layer: Helium

Action engine: idfc-coder

Validates: imports · patterns · schema

The Relationship

#A753LC5

Helium and idfc-coder are not the same system wearing two hats — they solve two different problems, and code generation only works well when both are present.

┌──────────────────────────────────────────────────────────┐
│  HELIUM      → the org's knowledge layer                  │
│               answers: "what exists, and how does it work?"│
│                                                            │
│  IDFC-CODER  → the action & generation engine              │
│               answers: "given what exists, what do I build?"│
│                                                            │
│  Helium without idfc-coder = a great search engine that    │
│  never writes anything.                                    │
│  idfc-coder without Helium = a fluent generator that writes │
│  confident, plausible, WRONG code.                          │
└──────────────────────────────────────────────────────────┘

How Helium Indexes the Codebase

#8DRC11E

Helium isn't a flat text search over files. It builds a knowledge graph across five dimensions, and a single query is answered by combining evidence from all of them at once.

1. CODE STRUCTURE GRAPH   — classes, methods, call chains, DI wiring
2. API CONTRACTS          — OpenAPI/Swagger specs: routes, request/response models, errors
3. DATABASE SCHEMAS       — tables, columns, migrations, indexes  (→ see Section 04)
4. CONFIG & BUSINESS LOGIC— application.yml values, thresholds, rules embedded in comments
5. HISTORICAL CONTEXT     — git history, linked Jira tickets, past PR discussions

  query → [vector search | keyword search | API-contract search |
            dependency-graph search | config search]  → ranked, merged result set

The point of the five-dimension design: a bare code search would find UpiPaymentService.java. Helium's combined search also surfaces the API contract it must satisfy, the config values it reads, the exception type it should throw, and the last time someone touched this exact logic — because a developer needs all of that to write the change correctly, not just the file.

How the LLM Actually Gets Context

#RTJ5PHT

This is the part that matters most: the LLM never talks to the codebase directly. Every piece of context it sees has already been fetched, ranked, and packaged by Helium before the prompt is built.

TICKET  →  idfc-coder asks Helium several targeted questions
           (e.g. "show current UpiPaymentService structure",
                 "how do I fetch customer category",
                 "what error codes already exist for payments")
           │
           ▼
HELIUM  →  returns a structured CONTEXT PACKAGE per question:
           current implementation · dependency to call · error-code
           patterns · config patterns · relevant DB columns ·
           matching test patterns · similar past commit
           │
           ▼
IDFC-CODER → deduplicates, prioritizes by task relevance, summarizes
             large files, and fits everything into the token budget
           │
           ▼
PROMPT  →  ticket + Helium's context package + explicit constraints
           ("use PaymentException, not Exception"; "follow existing
           constructor-injection pattern") → sent to the model
           │
           ▼
GENERATED CODE → idfc-coder asks Helium to VALIDATE it:
           "does CustomerProfileService really exist?"
           "is this error code actually new?"
           "does this config class match our existing pattern?"
           → hallucinations get caught here, before a human ever sees them

The last step is the one people usually miss: Helium isn't just a context provider before generation, it's also the fact-checker after generation. The LLM's output is only trusted once it has been checked back against the same knowledge graph that built the prompt.

Why this matters in practice

Ask the same model the same ticket with and without this pipeline, and the difference isn't subtle: wrong class names, wrong exception types, invented dependencies, and a rewritten-from-scratch PR — versus code that uses the bank's actual constructor-injection pattern, actual error codes, and actual service names, because it was handed the real ones instead of guessing.

Database Field Context — a Reasoned Design

#0HL9XPS

This part isn't spelled out in the source material — it's my own best-guess architecture for the piece you remembered: mandatory per-field documentation. Flagging it clearly as inferred, not confirmed.

A raw schema dump tells the LLM a column's name and type. It doesn't tell it the column's meaning — and "meaning" is exactly what a developer needs before writing code that touches it. If per-field documentation was a stated requirement, the most plausible reason is that Helium needs that documentation as raw material, the same way it needs code comments and Jira tickets. Here's how that most likely works end to end:

SOURCE (documentation is captured at write-time, not guessed later)
  ├── DDL migration comments:  COMMENT ON COLUMN upi_transactions.status IS '...'
  ├── companion data-dictionary.yaml per table, committed alongside the migration
  └── entity-class Javadoc / annotations mirroring the same description
           │
           ▼
GOVERNANCE GATE (keeps the documentation honest)
  ├── CI schema linter: new/changed column with no dictionary entry → PR blocked
  └── periodic drift check: Helium's schema crawler introspects the live DB
      catalog (JDBC metadata) and flags any column whose actual definition
      no longer matches what's documented
           │
           ▼
HELIUM ENRICHMENT (per column, not just per table)
  ├── business meaning          "tier used to compute the UPI transaction limit"
  ├── valid domain              ENUM('REGULAR','PREMIUM','MERCHANT')
  ├── sensitivity classification PII: no  |  regulated: yes (payments-adjacent)
  ├── related business rule      "premium tier caps at ₹2,00,000 — see IDFC-7890"
  ├── owning service             CustomerProfileService.getCustomerCategory()
  └── change history             last modified in commit ghi789, linked to IDFC-9012
           │
           ▼
DELIVERED TO THE LLM as a semantic card, not a type signature:
  "customer_category — ENUM, non-PII, determines UPI limit tier via
   PaymentLimitConfig, owned by CustomerProfileService, do not
   hardcode threshold values — read from config"

The mechanism that makes this trustworthy is the same pattern as the code-validation loop in Section 03: documentation alone drifts from reality over time, so Helium doesn't just index the data dictionary — it continuously checks the dictionary against the live schema and treats any mismatch as a governance failure, the same way an undocumented column would be. That closed loop is what lets the LLM treat a column description as ground truth instead of a comment that might be three years stale.

Inference, not confirmed spec

This design is a reasonable, consistent extension of the same indexing philosophy used elsewhere in the system (schema dimension already listed in Section 02, validation-against-ground-truth already used for code) — but it's my construction, not something stated outright in the source material. Worth saying explicitly if this comes up in an interview: "here's how I'd design it," not "here's exactly what we built."

Why It Matters

#EIMVIHC

Metric	Without Helium	With Helium
Correct class/method names	25–30%	92–95%
Import accuracy	40%	96%
Exception-handling pattern match	20%	90%
Developer rework time	2–3 hours	15–30 minutes
PR acceptance rate	35%	78%
Post-merge bug rate	18%	7%

The gap isn't model quality — it's the same DeepSeek Coder model either way. The entire difference is whether it was handed the bank's actual codebase facts or left to guess plausible-sounding ones.

Role Summary

#WI64CIY

HELIUM — the knowledge layer

Indexes code structure, API contracts, DB schema, config, and history
Answers "what exists and how does it connect"
Acts as the post-generation fact-checker, not just a pre-generation lookup

IDFC-CODER — the action engine

Orchestrates the ticket → context → prompt → PR flow
Decides what context is relevant and fits it to the token budget
Generates code, then re-checks its own output against Helium

Bottom line

The LLM itself never gets smarter about IDFC's codebase — it stays a general-purpose code model. What changes is what it's shown right before it answers. Helium's entire job is making sure that "what it's shown" is real: real class names, real error codes, real column meanings — not the model's best guess at what a bank's codebase probably looks like.