# ondc-official/pramaan architecture

> Architecture diagram of the GitHub repository ondc-official/pramaan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ondc-official/pramaan
- Repository: https://github.com/ondc-official/pramaan

## Overview

1. **Repository purpose**
   - This repo is not an application backend or frontend. It is the public asset/documentation repository for **Pramaan**, ONDC’s integration test bench.
   - Its main job is to define and publish **protocol test cases, schemas, and usage docs** for validating ONDC integrations.

2. **Primary architecture boundary**
   - The core boundary is between **Pramaan** and external ONDC participants:
     - **BAP** = Buyer App Platform
     - **BPP** = Seller/Provider App Platform
   - Pramaan sits as a **validation and testing harness** around protocol interactions, not as a business workflow system.

3. **Documentation layer**
   - `README.md` plus the `docs/` tree provide the human-facing product and onboarding material:
     - introduction
     - getting started
     - domain/support guidance
   - This suggests the repo serves both as a **test specification source** and a **supporting knowledge base**.

4. **Domain scope**
   - The only explicit test domain in the tree is **retail** under `testcases/retail/`.
   - That indicates the repo is organized by ONDC domain/use-case, and retail is one concrete protocol area covered here.

5. **Test case organization by participant role**
   - Retail test cases are split into:
     - `ret-bap/` for **Buyer App side** request flows
     - `ret-bpp/` for **Seller/Provider side** callback/response flows
   - This separation is important: the repo models both sides of the ONDC protocol conversation.

6. **BAP schema set**
   - `testcases/retail/ret-bap/` contains schema files for the buyer-initiated workflow:
     - `context.schema.js`
     - `search`, `select`, `init`, `confirm`, `update`, `cancel`, `track`, `info`
   - These files represent the **shape and constraints of outgoing protocol messages** generated by the Buyer App side.

7. **BPP schema set**
   - `testcases/retail/ret-bpp/` contains callback schemas for the provider side:
     - `context.schema.js`
     - `on_search`, `on_select`, `on_init`, `on_confirm`, `on_cancel`, `on_status`, `on_track`, `on_info`, `on_update`
     - `catalog_rejection.schema.js`
   - These model the **asynchronous response/callback contracts** expected from the Seller/Provider App.

8. **Protocol flow implied by the files**
   - The schema naming shows the end-to-end transaction lifecycle:
     - discovery/search
     - selection
     - initialization
     - confirmation
     - order status / tracking / updates
     - cancellation / info handling
   - Pramaan likely validates each hop independently, ensuring both request and callback payloads conform to ONDC expectations.

9. **Implementation style**
   - The schemas are JavaScript files, which implies the validation layer is likely built around **schema modules** rather than handwritten prose specs.
   - In architecture terms, these are the repo’s **machine-readable contract artifacts**.

10. **Operational and support surface**
   - `.github/workflows/auto-comment-on-issue.yml` adds lightweight GitHub automation for issue handling/support.
   - That reinforces that the repository also functions as a **community/support entry point**, not just a spec store.

11. **What is not present**
   - There is no visible application source, service orchestration code, database layer, or deployment manifests in this tree.
   - So the repo’s architecture is centered on **documentation + test definitions**, with the actual Pramaan runtime presumably living elsewhere.

12. **How to diagram it**
   - A good architecture diagram would show:
     - ONDC participant apps on both sides
     - Pramaan as the test/validation platform in the middle
     - retail domain schema artifacts feeding the validator
     - docs/support and GitHub issue automation as auxiliary surfaces
   - The key flow is **protocol messages ↔ schema validation ↔ callback validation ↔ result/support**.

Main entry points: [`testcases/retail/ret-bpp`](https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bpp) (BPP schemas), [`testcases/retail/ret-bap`](https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bap) (BAP schemas), [`testcases/retail`](https://github.com/ondc-official/pramaan/tree/master/testcases/retail) (Retail), [`.github/workflows/auto-comment-on-issue.yml.`](https://github.com/ondc-official/pramaan/blob/master/.github/workflows/auto-comment-on-issue.yml.) (Issue bot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Pramaan"]
  node_pramaan{{"Pramaan<br/>test-bench"}}
end

subgraph group_docs["Docs"]
  node_readme["README<br/>docs-entry<br/>[README.md]"]
  node_intro["Introduction<br/>overview-doc<br/>[introduction.md]"]
  node_getting_started["Getting started<br/>onboarding-doc"]
  node_domains_doc["Domains<br/>domain-docs"]
  node_support_doc["Support"]
end

subgraph group_tests["Retail tests"]
  node_retail_domain["Retail<br/>protocol-domain"]
  node_ret_bap["BAP schemas<br/>buyer-contracts"]
  node_bap_context["Context<br/>schema<br/>[context.schema.js]"]
  node_bap_flow["Buyer flow<br/>request-schemas<br/>[search.schema.js]"]
  node_ret_bpp["BPP schemas<br/>provider-contracts"]
  node_bpp_context["Context<br/>schema<br/>[context.schema.js]"]
  node_bpp_flow["Callback flow<br/>callback-schemas"]
  node_catalog_rejection["Rejection<br/>special-case-schema"]
end

subgraph group_support["Automation"]
  node_issue_bot["Issue bot<br/>github-action"]
end

subgraph group_external["External participants"]
  node_bap_app["Buyer app<br/>external-bap"]
  node_bpp_app["Seller app<br/>external-bpp"]
end

node_bap_app -->|"validated by"| node_ret_bap
node_bpp_app -->|"validated by"| node_ret_bpp
node_retail_domain -->|"contains"| node_ret_bap
node_retail_domain -->|"contains"| node_ret_bpp
node_ret_bap -->|"shares context"| node_bap_context
node_ret_bap -->|"defines flow"| node_bap_flow
node_ret_bpp -->|"shares context"| node_bpp_context
node_ret_bpp -->|"defines callbacks"| node_bpp_flow
node_ret_bpp -.->|"special case"| node_catalog_rejection
node_readme -->|"introduces"| node_pramaan
node_intro -->|"orients"| node_pramaan
node_getting_started -->|"guides"| node_pramaan
node_domains_doc -->|"describes"| node_retail_domain
node_support_doc -.->|"supported by"| node_issue_bot
node_issue_bot -.->|"supports"| node_pramaan
node_pramaan -->|"uses"| node_ret_bap
node_pramaan -->|"uses"| node_ret_bpp
node_pramaan -->|"tests"| node_bap_app
node_pramaan -->|"tests"| node_bpp_app

click node_readme "https://github.com/ondc-official/pramaan/blob/master/README.md"
click node_intro "https://github.com/ondc-official/pramaan/blob/master/introduction.md"
click node_getting_started "https://github.com/ondc-official/pramaan/tree/master/docs/getting-started"
click node_domains_doc "https://github.com/ondc-official/pramaan/tree/master/docs/domains"
click node_support_doc "https://github.com/ondc-official/pramaan/tree/master/docs/support"
click node_retail_domain "https://github.com/ondc-official/pramaan/tree/master/testcases/retail"
click node_ret_bap "https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bap"
click node_bap_context "https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bap/context.schema.js"
click node_bap_flow "https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bap/search.schema.js"
click node_ret_bpp "https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bpp"
click node_bpp_context "https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/context.schema.js"
click node_bpp_flow "https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/on_search.schema.js"
click node_catalog_rejection "https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/catalog_rejection.schema.js"
click node_issue_bot "https://github.com/ondc-official/pramaan/blob/master/.github/workflows/auto-comment-on-issue.yml."

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_pramaan toneBlue
class node_readme,node_intro,node_getting_started,node_domains_doc,node_support_doc toneAmber
class node_retail_domain,node_ret_bap,node_bap_context,node_bap_flow,node_ret_bpp,node_bpp_context,node_bpp_flow,node_catalog_rejection toneMint
class node_issue_bot toneRose
class node_bap_app,node_bpp_app toneIndigo
```

## Components

### Pramaan

Repository boundary and central test bench concept

- **Pramaan**: test-bench · Integration test bench and validation boundary for ONDC protocol interactions

### Docs

Human-facing introduction, onboarding, and support material

- [README](https://github.com/ondc-official/pramaan/blob/master/README.md): docs-entry · Primary repository overview and entry point · `README.md`
- [Introduction](https://github.com/ondc-official/pramaan/blob/master/introduction.md): overview-doc · High-level product and usage introduction · `introduction.md`
- [Getting started](https://github.com/ondc-official/pramaan/tree/master/docs/getting-started): onboarding-doc · Setup and first-use guidance · `docs/getting-started`
- [Domains](https://github.com/ondc-official/pramaan/tree/master/docs/domains): domain-docs · Domain-oriented documentation set · `docs/domains`
- [Support](https://github.com/ondc-official/pramaan/tree/master/docs/support): support-docs · Support and help guidance · `docs/support`

### Retail tests

Machine-readable protocol contracts for the retail domain

- [Retail](https://github.com/ondc-official/pramaan/tree/master/testcases/retail): protocol-domain · Retail ONDC test domain · `testcases/retail`
- [BAP schemas](https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bap): buyer-contracts · Buyer App Platform request contract set · `testcases/retail/ret-bap`
- [Context](https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bap/context.schema.js): schema · Shared buyer-side context schema · `testcases/retail/ret-bap/context.schema.js`
- [Buyer flow](https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bap/search.schema.js): request-schemas · Buyer-initiated lifecycle schemas such as search, select, init, confirm, update, cancel, track, and info · `testcases/retail/ret-bap/search.schema.js`
- [BPP schemas](https://github.com/ondc-official/pramaan/tree/master/testcases/retail/ret-bpp): provider-contracts · Seller/Provider App Platform callback contract set · `testcases/retail/ret-bpp`
- [Context](https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/context.schema.js): schema · Shared provider-side context schema · `testcases/retail/ret-bpp/context.schema.js`
- [Callback flow](https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/on_search.schema.js): callback-schemas · Provider callbacks such as on_search, on_select, on_init, on_confirm, on_status, on_track, on_info, and on_update · `testcases/retail/ret-bpp/on_search.schema.js`
- [Rejection](https://github.com/ondc-official/pramaan/blob/master/testcases/retail/ret-bpp/catalog_rejection.schema.js): special-case-schema · Provider-side catalog rejection contract · `testcases/retail/ret-bpp/catalog_rejection.schema.js`

### Automation

Lightweight GitHub issue automation

- [Issue bot](https://github.com/ondc-official/pramaan/blob/master/.github/workflows/auto-comment-on-issue.yml.): github-action · GitHub workflow for automatic issue commenting · `.github/workflows/auto-comment-on-issue.yml.`

### External participants

ONDC-side systems that Pramaan validates

- **Buyer app**: external-bap · External Buyer App Platform participating in protocol tests
- **Seller app**: external-bpp · External Seller/Provider App Platform participating in protocol tests

## Connections

- Buyer app → BAP schemas: validated by · Buyer-side requests are checked against retail BAP schemas
- Seller app → BPP schemas: validated by · Provider-side callbacks are checked against retail BPP schemas
- Retail → BAP schemas: contains · Retail domain organizes buyer-side test contracts
- Retail → BPP schemas: contains · Retail domain organizes provider-side test contracts
- BAP schemas → Context: shares context · Buyer-side workflows reuse the shared context contract
- BAP schemas → Buyer flow: defines flow · Buyer-side lifecycle schemas define outgoing protocol messages
- BPP schemas → Context: shares context · Provider-side callbacks reuse the shared context contract
- BPP schemas → Callback flow: defines callbacks · Provider-side lifecycle schemas define asynchronous responses
- BPP schemas → Rejection: special case · Provider-side catalog rejection handling is modeled separately
- README → Pramaan: introduces · Repository entry point explains the test bench purpose
- Introduction → Pramaan: orients · High-level overview supports onboarding to the repository
- Getting started → Pramaan: guides · Getting started docs support use of the test bench
- Domains → Retail: describes · Domain documentation connects to retail test coverage
- Support → Issue bot: supported by · Support surface is reinforced by GitHub automation
- Issue bot → Pramaan: supports · Workflow provides lightweight repository support automation
- Pramaan → BAP schemas: uses · Pramaan relies on machine-readable buyer-side contracts
- Pramaan → BPP schemas: uses · Pramaan relies on machine-readable provider-side contracts
- Pramaan → Buyer app: tests · Pramaan validates protocol messages from buyer platforms
- Pramaan → Seller app: tests · Pramaan validates protocol callbacks from provider platforms