---
title: core-archtecture
collection: git-wiki
author: Suraj Kumar Jha
updated: 2026-09-11
source: https://docs.chaicode.com/git-wiki/core-archtecture
---

# core-archtecture

![On the far left, a user device box sends a 'POST /api/index' arrow to an Express API box. Express splits the action into two arrows: a dotted arrow returns '200 OK + jobId #101' immediately back to the user, while a solid arrow sends 'repo/index.requested' to a large Inngest engine box on the right. Below the user box, a circular dotted loop labeled 'GET /jobId #101 (polling)' queries Express repeatedly.](https://docs.chaicode.com/cdn-cgi/image/width=1600,format=auto,fit=scale-down/assets/c2819e8adafcb6283e426bd5fe19895cf0393274af94db2c303624dc1d455309.png)

Why Async: Instant Receipts, Slow Cooking — When you order a pizza on Swiggy, the app gives you an Order ID in 50 milliseconds instead of freezing your screen for 25 minutes while the kitchen bakes it.
Similarly, an Express server will timeout if an HTTP request stays open for 2 minutes while downloading, splitting, and embedding a GitHub codebase.
Calling `POST /api/index` creates a job marked 'queued', fires a background event to Inngest, and returns a `jobId` immediately.
The client browser polls `GET /:jobId` every 2 seconds to check if status flipped from 'running' to 'completed'.

![A vertical stack of three rounded step boxes inside an Inngest container. Box 1 'fetch-github-files' has a green checkmark, Box 2 'chunk-files' has a green checkmark, and Box 3 'save-to-pinecone' displays an orange warning triangle. A curved retry arrow loops directly from an Inngest scheduler node outside the container into Box 3, completely bypassing Box 1 and Box 2.](https://docs.chaicode.com/cdn-cgi/image/width=1600,format=auto,fit=scale-down/assets/83fdd1705be1613eeecd25322e7412302f9054b4abbdedd4036a74944753a8f2.png)

Step Checkpoints: Never Start Over — If an IRCTC Tatkal payment fails after seat allocation, you want the app to retry only the UPI payment, not restart coach selection from zero.
Inngest wraps every heavy operation inside `step.run()`, checkpointing intermediate outputs to durable storage.
If GitHub file download succeeds but Pinecone vector upsert fails due to a network glitch, Inngest retries ONLY the Pinecone step.
This prevents wasted OpenAI API billing and stops your app from exhausting GitHub's 5,000 requests-per-hour rate limit.

![A horizontal 4-stage pipeline flowing left to right. Node 1 shows a GitHub Octocat icon outputting '200 raw files', pointing to Node 2 'LangChain Splitter' producing '1000-char chunks (150 overlap)'. An arrow connects Node 2 to Node 3 'OpenAI Embeddings' generating vector arrays, which point into Node 4 'Pinecone Vector DB' labeled with namespace tag 'owner-repo'.](https://docs.chaicode.com/cdn-cgi/image/width=1600,format=auto,fit=scale-down/assets/3712f92b3bf48cc812e5fd74a08707e7f2bac9e6238a1c2bf8cdaf43b7fecae8.png)

Write Path: Indexing Repository Code — Triggered by `repo/index.requested`, Step 1 fetches up to 200 source files from GitHub's tree API.
Step 2 runs locally on the CPU, splitting files into 1,000-character LangChain text chunks with a 150-character overlap to preserve syntax boundaries.
Step 3 sends chunks to OpenAI `text-embedding-3-small` and upserts vectors into Pinecone under an isolated namespace formatted as `owner-repo`.
Once vectors are written, the job marks itself 'completed' and records final metrics like 140 files and 520 chunks.

![A central box labeled 'ask-question (Inngest)'. On its left, an arrow sends an embedded query vector into a cylinder labeled 'Pinecone: owner-repo', which returns an arrow with 'Top 5 Chunks (k=5)'. These 5 chunks feed into a 'GPT-4o-mini' box on the right, which outputs two distinct arrows labeled 'Markdown Answer' and 'Source File List' into a completed job store box at the bottom.](https://docs.chaicode.com/cdn-cgi/image/width=1600,format=auto,fit=scale-down/assets/0b3a3c65eb22ed6a05f213a569cf23d47e5e5115654983bc6b4f17e7b828aee0.png)

Read Path: RAG Similarity Search — When a developer submits a question via `POST /api/chat`, Express responds with HTTP 202 and delegates work to `ask-question`.
This function never touches GitHub; it embeds the user query and asks Pinecone for the top 5 (k=5) closest vector chunks inside that repo's namespace.
It injects those 5 code chunks into a strict system prompt: 'Answer using this repo context only' to eliminate AI hallucinations.
GPT-4o-mini generates the response within 2 to 4 seconds, returning both the Markdown answer and the specific source file paths.

![Two parallel horizontal tracks converging on a central cylinder labeled 'Pinecone Namespace: owner-repo'. The top track shows 'Write Path: index-repo' with a downward green write arrow pushing 500 vector chunks into the cylinder. The bottom track shows 'Read Path: ask-question' with a bidirectional blue query arrow reading 5 chunks from the cylinder. A red 'No Direct Call' line separates the two worker tracks.](https://docs.chaicode.com/cdn-cgi/image/width=1600,format=auto,fit=scale-down/assets/17e92f95212768a27402cda0906be84e1f4083416b8bc642600591f410e637f5.png)

Two Paths, One Vector Namespace — The write path (`index-repo`) runs once per repository commit, converting hundreds of source files into searchable vectors.
The read path (`ask-question`) runs hundreds of times as teammates ask multiple questions about the codebase.
Neither function directly invokes the other; their only shared touchpoint is the isolated Pinecone namespace `owner-repo`.
If a user queries a repository before indexing completes, Pinecone returns 0 vectors and the LLM safely reports empty context.