# abhi9199-tech42/scdl-rag-enhanced-architecture architecture

> Architecture diagram of the GitHub repository abhi9199-tech42/scdl-rag-enhanced-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhi9199-tech42/scdl-rag-enhanced-architecture
- Repository: https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture

## Overview

This repository is a hybrid monorepo for a contradiction-aware RAG system. The main production-facing code is in `src/` (TypeScript), while `api/` and `embedding/` contain Python service components, and `isre/`, `urcm/`, and `reference/` hold reference implementations and migration/validation material.

1. **External entry points**
   The system is consumed by Python and JavaScript SDKs (`sdk/python`, `sdk/javascript`), direct HTTP clients, and the test/load scripts. The documented API surface is a detection service that accepts a question, answer, and source documents, then returns a hallucination verdict, score, and explanation.

2. **HTTP/API boundary**
   The TypeScript server in `src/api/` is the main request edge: `server.ts`, `routes.ts`, `middleware/auth.ts`, `middleware/rateLimit.ts`, `validation.ts`, `swagger.ts`, and `metrics.ts` define request handling, auth, throttling, schema validation, API docs, and observability. Async endpoints are part of this boundary as well.

3. **Orchestration layer**
   `src/system/core.ts` and `src/system/performance.ts` coordinate runtime behavior and performance-sensitive paths. This is the point where request-level work is handed off to retrieval, context assembly, and contradiction analysis, and where async/background processing is likely coordinated.

4. **Context and retrieval pipeline**
   `src/context/assembler.ts` and `src/retrieval/engine.ts` form the evidence-preparation path. Documents and query material are normalized, assembled into a working context, and then scored/retrieved before the reasoning layers operate on them.

5. **Storage and persistence**
   `src/storage/` provides two backing modes (`memory_store.ts` and `file_store.ts`) plus deduplication logic. The checked-in `data/vector_store.json` indicates a local vector/cache artifact rather than a separate database service, so persistence is lightweight and embedded in-process or file-backed.

6. **Hallucination/contradiction reasoning**
   The core reasoning subsystems are split into `src/isre/` and `src/urcm/`. `src/isre/bridge.ts`, `src/isre/processor.ts`, and the compression/graph/multilang modules implement semantic reasoning, while `src/urcm/processor.ts` and `src/urcm/contradiction/*` handle contradiction detection and resolution. This is the main analytic boundary of the system.

7. **Explainability and audit trail**
   `src/audit/explainable.ts` and `src/audit/trail.ts` capture why a result was produced, not just the result itself. This is important because the product’s output is meant to be human-readable and auditable, especially for detected contradictions and auto-fix suggestions.

8. **Shared primitives and utilities**
   Common types, IDs, logging, and vector utilities live in `src/types`, `src/utils/id.ts`, `src/utils/logger.ts`, and `src/utils/vector.ts`. These are cross-cutting support modules used by API, retrieval, storage, and reasoning code.

9. **Python service components**
   The `api/` and `embedding/` directories are separate Python service runtimes with their own requirements and Dockerfiles. The README describes them as the API service and the embedding/NLI inference service, so in deployment diagrams they should be treated as distinct services connected over HTTP rather than as libraries.

10. **Reference implementations and compatibility layers**
   `isre/`, `urcm/`, and the large `reference/` subtree mirror the same architecture in Python and include validation suites, docs, and examples. These are useful for understanding intent and for migration/benchmarking, but they are not the only runtime path.

11. **Offline evaluation and performance harness**
   `experiments/` and `loadtest/` contain benchmark runners, datasets, CSV/MD reports, and pressure tests. These are an offline analytics boundary: they exercise the API and model services to measure recall, throughput, endurance, and auto-fix behavior.

12. **Deployment and packaging**
   Docker is first-class (`docker/api.Dockerfile`, `docker/embedding.Dockerfile`, `docker/docker-compose.yml`), and CI is defined in `.github/workflows/ci.yml`. The repo also ships docs/landing pages and SDK packaging, so the architecture spans service runtime, client libraries, and documentation/static site delivery.

In diagram terms, the key flow is: client/SDK → API gateway/server → validation/auth/rate limit → context assembly/retrieval/storage → ISRE/URCM reasoning and contradiction detection → audit/explanation → response, with a separate embedding/inference service and offline evaluation/load-testing tooling around it.

Main entry points: [`src/api`](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/api) (API Server), [`src/types`](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/types) (Shared Primitives), [`src/system`](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/system) (System Core), [`src/isre`](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/isre) (ISRE Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients & SDKs"]
  node_sdk_py["Python SDK<br/>client library"]
  node_sdk_js["JS SDK<br/>client library"]
  node_http_clients["HTTP Clients<br/>direct client"]
end

subgraph group_ts["TypeScript Runtime"]
  node_ts_api["API Server<br/>http boundary"]
  node_ts_system["System Core<br/>orchestration"]
  node_ts_context["Context Builder<br/>context pipeline"]
  node_ts_retrieval["Retrieval Engine"]
  node_ts_storage[("Storage Layer<br/>persistence")]
  node_ts_isre{{"ISRE Engine<br/>semantic reasoning"}}
  node_ts_urcm{{"URCM Engine<br/>contradiction reasoning"}}
  node_ts_audit["Audit Trail<br/>explainability"]
  node_ts_shared["Shared Primitives<br/>cross-cutting core"]
end

subgraph group_py["Python Services"]
  node_py_api["Python API"]
  node_py_embed["Embedding Service"]
end

subgraph group_ref["Reference Material"]
  node_ref_isre["ISRE Reference<br/>reference impl"]
  node_ref_urcm["URCM Reference<br/>reference impl"]
end

subgraph group_ops["Offline Ops"]
  node_offline_eval["Eval Harness<br/>benchmarking"]
  node_loadtest["Load Tests<br/>pressure testing"]
  node_deploy["Deploy Assets<br/>deployment"]
  node_docs["Docs Site<br/>documentation"]
end

node_sdk_py -->|"detect"| node_ts_api
node_sdk_js -->|"detect"| node_ts_api
node_http_clients -->|"HTTP request"| node_ts_api
node_ts_api -->|"dispatch"| node_ts_system
node_ts_system -->|"assemble"| node_ts_context
node_ts_system -->|"retrieve"| node_ts_retrieval
node_ts_system -->|"analyze"| node_ts_isre
node_ts_system -->|"contradict"| node_ts_urcm
node_ts_context -->|"read/write"| node_ts_storage
node_ts_retrieval -->|"fetch"| node_ts_storage
node_ts_isre -->|"explain"| node_ts_audit
node_ts_urcm -->|"audit"| node_ts_audit
node_ts_shared -->|"support"| node_ts_api
node_ts_shared -->|"support"| node_ts_context
node_ts_shared -->|"support"| node_ts_retrieval
node_ts_shared -->|"support"| node_ts_isre
node_ts_shared -->|"support"| node_ts_urcm
node_py_api -->|"HTTP"| node_py_embed
node_ref_isre -.->|"reference"| node_ts_isre
node_ref_urcm -.->|"reference"| node_ts_urcm
node_offline_eval -->|"exercise"| node_ts_api
node_loadtest -->|"stress"| node_ts_api
node_deploy -->|"build/run"| node_py_api
node_deploy -->|"build/run"| node_py_embed
node_docs -.->|"describe"| node_ts_api
node_docs -.->|"describe"| node_ts_isre
node_docs -.->|"describe"| node_ts_urcm

click node_sdk_py "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/sdk/python"
click node_sdk_js "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/sdk/javascript"
click node_ts_api "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/api"
click node_ts_system "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/system"
click node_ts_context "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/context"
click node_ts_retrieval "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/retrieval"
click node_ts_storage "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/storage"
click node_ts_isre "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/isre"
click node_ts_urcm "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/urcm"
click node_ts_audit "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/audit"
click node_ts_shared "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/types"
click node_py_api "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/api"
click node_py_embed "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/embedding"
click node_ref_isre "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/reference/isre"
click node_ref_urcm "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/reference/urcm"
click node_offline_eval "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/experiments"
click node_loadtest "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/loadtest"
click node_deploy "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/docker"
click node_docs "https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk_py,node_sdk_js,node_http_clients toneBlue
class node_ts_api,node_ts_system,node_ts_context,node_ts_retrieval,node_ts_storage,node_ts_isre,node_ts_urcm,node_ts_audit,node_ts_shared toneAmber
class node_py_api,node_py_embed toneMint
class node_ref_isre,node_ref_urcm toneRose
class node_offline_eval,node_loadtest,node_deploy,node_docs toneIndigo
```

## Components

### Clients & SDKs

Entry points that call the detection system

- [Python SDK](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/sdk/python): client library · Python client wrapper for the detection API · `sdk/python`
- [JS SDK](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/sdk/javascript): client library · JavaScript client wrapper for the detection API · `sdk/javascript`
- **HTTP Clients**: direct client · Direct callers using the HTTP surface

### TypeScript Runtime

Main production-facing implementation

- [API Server](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/api): http boundary · Main request edge for detection and async endpoints · `src/api`
- [System Core](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/system): orchestration · Coordinates request handling and runtime flow · `src/system`
- [Context Builder](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/context): context pipeline · Normalizes and assembles evidence for reasoning · `src/context`
- [Retrieval Engine](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/retrieval): retrieval · Scores and retrieves source material before analysis · `src/retrieval`
- [Storage Layer](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/storage): persistence · In-process and file-backed stores with deduplication · `src/storage`
- [ISRE Engine](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/isre): semantic reasoning · Intent and semantic reasoning subsystem · `src/isre`
- [URCM Engine](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/urcm): contradiction reasoning · Contradiction detection and resolution subsystem · `src/urcm`
- [Audit Trail](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/audit): explainability · Captures explanations and provenance for outputs · `src/audit`
- [Shared Primitives](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/src/types): cross-cutting core · Common types, IDs, logging, and vector helpers · `src/types`

### Python Services

Separate service runtimes for API and embeddings

- [Python API](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/api): service · Python service component for API-facing runtime · `api`
- [Embedding Service](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/embedding): service · Python inference service for embeddings and NLI · `embedding`

### Reference Material

Migration and validation implementations

- [ISRE Reference](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/reference/isre): reference impl · Python reference implementation and validation suite · `reference/isre`
- [URCM Reference](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/reference/urcm): reference impl · Python reference implementation and integration bridge · `reference/urcm`

### Offline Ops

Evaluation, load testing, and deployment assets

- [Eval Harness](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/experiments): benchmarking · Experiments for benchmark runs and report generation · `experiments`
- [Load Tests](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/loadtest): pressure testing · Async, HTTP, endurance, and stress testing scripts · `loadtest`
- [Deploy Assets](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/docker): deployment · Docker and compose definitions plus CI workflow · `docker`
- [Docs Site](https://github.com/abhi9199-tech42/scdl-rag-enhanced-architecture/tree/main/docs): documentation · Product, API, system, and deployment documentation · `docs`

## Connections

- Python SDK → API Server: detect · Python SDK calls the main detection API
- JS SDK → API Server: detect · JavaScript SDK calls the main detection API
- HTTP Clients → API Server: HTTP request · Direct clients hit the API boundary
- API Server → System Core: dispatch · API layer hands work to orchestration
- System Core → Context Builder: assemble · Runtime prepares evidence context
- System Core → Retrieval Engine: retrieve · Runtime invokes scoring and retrieval
- System Core → ISRE Engine: analyze · Runtime forwards evidence to semantic reasoning
- System Core → URCM Engine: contradict · Runtime forwards evidence to contradiction analysis
- Context Builder → Storage Layer: read/write · Context assembly uses local persistence and deduplication
- Retrieval Engine → Storage Layer: fetch · Retrieval reads cached or file-backed vectors
- ISRE Engine → Audit Trail: explain · Reasoning contributes to human-readable explanation
- URCM Engine → Audit Trail: audit · Contradiction detection contributes trace and rationale
- Shared Primitives → API Server: support · Shared primitives underpin request handling
- Shared Primitives → Context Builder: support · Shared primitives underpin context assembly
- Shared Primitives → Retrieval Engine: support · Shared primitives underpin retrieval logic
- Shared Primitives → ISRE Engine: support · Shared primitives underpin ISRE reasoning
- Shared Primitives → URCM Engine: support · Shared primitives underpin URCM reasoning
- Python API → Embedding Service: HTTP · Python service boundary connects to embedding/NLI inference
- ISRE Reference → ISRE Engine: reference · Reference implementation mirrors ISRE architecture
- URCM Reference → URCM Engine: reference · Reference implementation mirrors URCM architecture
- Eval Harness → API Server: exercise · Benchmark runners drive the production API
- Load Tests → API Server: stress · Pressure tests exercise request paths and throughput
- Deploy Assets → Python API: build/run · Deployment assets package the Python API service
- Deploy Assets → Embedding Service: build/run · Deployment assets package the embedding service
- Docs Site → API Server: describe · Documentation explains the API and system contracts
- Docs Site → ISRE Engine: describe · Documentation explains the ISRE reasoning layer
- Docs Site → URCM Engine: describe · Documentation explains the URCM contradiction layer