# ondc-official/ondc-sdk architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, microservice-based reference Buyer App (ONDC SDK Buyer App) that implements the demand-side (BAP) of the ONDC network.
- It provides a React/Redux frontend, Node.js “Client API” and “IGM” services, a Python-based ONDC protocol layer, ancillary Flask services (MMI geolocation, Bugzilla ticketing, catalog ingestion), all composed via Docker-Compose.

##### File Structure
- Top-level submodules:
- biap-app-ui-front (ReactJS app served by Nginx)
- biap-client-node-js (NodeJS BAP API layer)
- biap-igm-node-js (NodeJS IGM API layer)
- py-ondc-protocol (Python ONDC protocol implementation)
- ondc-mmi-service (Python Flask MMI geolocation)
- biap-bugzilla-service (Python Flask bug-ticket service)
- catalog-service (Python Flask catalog ingestion/search)
- Configuration & orchestration:
- docker-compose*.yaml, init-letsencrypt.sh, .env files
- deploying_ansible/ (Ansible playbooks for production)
- CI/utility scripts: check_for_latest_commit_and_build.py, NSDL Postman collection.

##### README
- Confirms microservice architecture: protocol layer (Python), client API (NodeJS), front app (React+Nginx), ancillary APIs (Flask).
- Tech stack: React, Redux, NodeJS/Express, Python/Flask, MongoDB, Nginx, Docker, Ansible.
- External integrations: ONDC registry/network, Juspay (payment), MapMyIndia (geolocation), Firebase Auth, Bugzilla.

##### Main Components & Their Interactions
a. Frontend Layer
- biap-app-ui-front: React/Redux SPA served by Nginx reverse proxy.
- Talks to → NodeJS BAP API via HTTP(S).

b. Client API Layer (NodeJS)
- biap-client-node-js: Exposes BAP REST endpoints (/search, /on_search, /init, /on_init, etc.).
- biap-igm-node-js: Exposes IGM-related endpoints for order/item grievances.
- Forwards ONDC-compliant messages to → py-ondc-protocol or ancillary services.

c. Protocol Layer (Python)
- py-ondc-protocol: Implements ONDC 1.2.0 protocol, signs messages, handles encryption, communicates with external ONDC networks (BPPs, registry).

d. Ancillary Microservices (Python Flask)
- ondc-mmi-service: Geolocation, PIN code lookup via MapMyIndia APIs.
- biap-bugzilla-service: Ticket management via embedded Bugzilla container.
- catalog-service: Catalog ingestion, indexing, search.

e. Data Storage
- MongoDB cluster/container for persisting user sessions, catalogs, orders, logs.

f. External Services
- ONDC network (registry, BPPs)
- Juspay payment gateway
- Firebase Authentication
- MapMyIndia APIs
- Bugzilla (self-hosted container)

g. Infrastructure & Deployment
- Docker-Compose bundles all microservices and MongoDB locally.
- Nginx serves the React app and routes API traffic.
- Ansible playbooks (deploying_ansible/) for production rollout.

##### Architectural Patterns & Design Principles
- Microservices: single-responsibility services, each in its own container.
- BFF (Backend-For-Frontend) pattern: NodeJS layer tailored to React UI.
- Protocol-Adapter: Python protocol layer abstracts ONDC messaging.
- 12-Factor app principles: environment-driven configurations, containerization, submodules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Browser)"]:::external
    User -->|"HTTP/HTTPS"| Nginx

    %% Infrastructure Layer
    Nginx["Nginx Reverse Proxy"]:::infra
    Nginx -->|serves| React
    Nginx -->|routes API| BAPAPI
    Nginx -->|routes API| IGMAPI

    %% Frontend Layer
    React["React/Redux UI"]:::frontend
    click React "https://github.com/ondc-official/ondc-sdk/tree/main/biap-app-ui-front/"

    %% Backend Microservices
    subgraph "Backend Services (Docker Network)"
        direction TB
        BAPAPI["BAP API (NodeJS/Express)"]:::backend
        IGMAPI["IGM API (NodeJS/Express)"]:::backend
        Protocol["ONDC Protocol (Python)"]:::backend
        GeoSvc["Geolocation Service (Flask)"]:::backend
        BugSvc["Bug Ticket Service (Flask)"]:::backend
        Catalog["Catalog Service (Flask)"]:::backend
        DB["MongoDB"]:::database

        React -->|API calls| BAPAPI
        React -->|API calls| IGMAPI
        BAPAPI -->|forwards ONDC messages| Protocol
        IGMAPI -->|forwards grievances| Protocol
        BAPAPI -->|search/init calls| Catalog
        BAPAPI -->|logs/orders| DB
        IGMAPI -->|logs/grievances| DB
        Protocol -->|persistence| DB
        GeoSvc -->|lookup| MapMyIndia
        BAPAPI -->|geolocation| GeoSvc
        BAPAPI -->|auth| Firebase
        BAPAPI -->|payments| Juspay
        BugSvc -->|ticket ops| Bugzilla
        BAPAPI -->|bug tickets| BugSvc
        Catalog -->|ingest/index| DB
        Catalog -->|search| DB

        Protocol -->|communicates| ONDCNet
    end

    %% External Systems
    subgraph "External Integrations"
        direction TB
        ONDCNet["ONDC Network"]:::external
        Juspay["Juspay Payment Gateway"]:::external
        Firebase["Firebase Auth"]:::external
        MapMyIndia["MapMyIndia APIs"]:::external
        Bugzilla["Bugzilla (Self-hosted)"]:::external
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Config"
        direction TB
        Compose["Docker-Compose Configs"]:::orchestration
        Ansible["Ansible Playbooks"]:::orchestration
        Utils["CI/Utility Scripts"]:::orchestration
        Docs["Global Config & Docs"]:::orchestration

        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/docker-compose.yaml"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/docker-compose-for-local.yaml"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/docker-compose-with-images.yaml"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/docker-compose-without-ssl.yaml"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/.env-local"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/.env-example"
        click Compose "https://github.com/ondc-official/ondc-sdk/blob/main/init-letsencrypt.sh"
        click Ansible "https://github.com/ondc-official/ondc-sdk/tree/main/deploying_ansible/"
        click Utils "https://github.com/ondc-official/ondc-sdk/blob/main/check_for_latest_commit_and_build.py"
        click Utils "https://github.com/ondc-official/ondc-sdk/blob/main/nsdl_postman.collection"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/README.md"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/SETUP.md"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/baip-app-protocol-application.yml"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/LICENSE.md"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/.gitignore"
        click Docs "https://github.com/ondc-official/ondc-sdk/blob/main/.gitmodules"
        click BAPAPI "https://github.com/ondc-official/ondc-sdk/tree/main/biap-client-node-js/"
        click IGMAPI "https://github.com/ondc-official/ondc-sdk/tree/main/biap-igm-node-js/"
        click Protocol "https://github.com/ondc-official/ondc-sdk/tree/main/py-ondc-protocol/"
        click GeoSvc "https://github.com/ondc-official/ondc-sdk/tree/main/ondc-mmi-service/"
        click BugSvc "https://github.com/ondc-official/ondc-sdk/tree/main/biap-bugzilla-service/"
        click Catalog "https://github.com/ondc-official/ondc-sdk/tree/main/catalog-service/"
    end

    %% Styles
    classDef frontend fill:#D0EBFF,stroke:#1E90FF,color:#000;
    classDef backend fill:#E6F4EA,stroke:#28A745,color:#000;
    classDef database fill:#FFF3CD,stroke:#FFC107,color:#000;
    classDef external fill:#E9ECEF,stroke:#6C757D,color:#000;
    classDef infra fill:#F0F8FF,stroke:#17A2B8,color:#000;
    classDef orchestration fill:#FFE5D9,stroke:#FD7E14,color:#000;
```
