# kkorel/p2p-trading architecture

> Architecture diagram of the GitHub repository kkorel/p2p-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kkorel/p2p-trading
- Repository: https://github.com/kkorel/p2p-trading

## Overview

This is a Beckn-based peer-to-peer renewable-energy marketplace: prosumers list hourly surplus, buyers discover and purchase offers, and delivery is checked before settlement and trust updates. The main journey runs from the web app through the combined buyer/seller API, catalog discovery, transaction callbacks, and order handling. Oorja chat, automated trading, credential verification, weather/solar analysis, and optional ledger integration are distinct product capabilities. Some subsystem links are documented in the README or SOURCE INDEX; unsampled internals are not inferred beyond that evidence.

Main entry points: [`packages/bap/src/routes.ts`](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/routes.ts) (Buyer API), [`packages/bap/src/seller-routes.ts`](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-routes.ts) (Seller API), [`packages/bap/src/auth-routes.ts`](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/auth-routes.ts) (Authentication routes), [`packages/bap/src/chat-routes.ts`](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat-routes.ts) (Chat routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Trading pages<br/>[page.tsx]"]
  node_chatui["Oorja interface<br/>[chat-page.tsx]"]
  node_chatapi["Chat routes<br/>[chat-routes.ts]"]
  node_agent["Oorja agent<br/>[agent.ts]"]
  node_tradingagent["Chat trading tools<br/>[trading-agent.ts]"]
  node_llm["LLM fallback<br/>[llm-fallback.ts]"]
  node_voice["Speech services<br/>[sarvam-stt.ts]"]
end

subgraph group_trading["Marketplace trading"]
  node_baproutes["Buyer API<br/>[routes.ts]"]
  node_sellerroutes["Seller API<br/>[seller-routes.ts]"]
  node_catalog["Seller catalog<br/>[seller-catalog.ts]"]
  node_orders["Order handling<br/>[seller-orders.ts]"]
  node_callbacks["Buyer callbacks<br/>[callbacks.ts]"]
  node_txstate["Transaction state<br/>[state.ts]"]
  node_cds["External catalog"]
  node_discom["Mock DISCOM<br/>[discom-mock.ts]"]
  node_ledger["Trade ledger<br/>[ledger.ts]"]
end

subgraph group_identity["Identity and intelligence"]
  node_auth["Authentication routes<br/>[auth-routes.ts]"]
  node_middleware["Session middleware<br/>[auth.ts]"]
  node_vc["Credential verifier<br/>[verifier.ts]"]
  node_solar["Solar analysis<br/>[solar-api.ts]"]
  node_automate["Auto-trade agents<br/>[buyer-agent.ts]"]
  node_weather["Weather service<br/>[weather-service.ts]"]
end

subgraph group_platform["Shared platform"]
  node_store[("Postgres and Redis<br/>[prisma.ts]")]
  node_beckn["Beckn secure client<br/>[secure-client.ts]"]
  node_trust["Trust engine<br/>[trust-engine.ts]"]
end

node_prosumer(("Buyer or seller"))

node_prosumer -->|"uses"| node_web
node_web -->|"calls trading API"| node_baproutes
node_prosumer -->|"uses"| node_chatui
node_chatui -.->|"sends chat"| node_chatapi
node_chatapi -->|"processes message"| node_agent
node_agent -->|"invokes trading tools"| node_tradingagent
node_agent -->|"requests fallback"| node_llm
node_chatapi -->|"transcribes audio"| node_voice
node_baproutes -->|"updates transaction"| node_txstate
node_baproutes -->|"discovers offers"| node_cds
node_baproutes -.->|"sends Beckn messages"| node_beckn
node_sellerroutes -->|"reads catalog"| node_catalog
node_sellerroutes -->|"updates order"| node_orders
node_sellerroutes -->|"reads transaction"| node_txstate
node_sellerroutes -->|"publishes catalog"| node_cds
node_baproutes -->|"receives async response"| node_callbacks
node_sellerroutes -.->|"requests delivery check"| node_discom
node_discom -->|"informs trust updates"| node_trust
node_baproutes -->|"records confirmed trades"| node_ledger
node_auth -->|"protects endpoints"| node_middleware
node_middleware -->|"loads user"| node_store
node_auth -->|"creates session and reads profile"| node_store
node_auth -.->|"verifies credentials"| node_vc
node_auth -->|"requests solar analysis"| node_solar
node_automate -->|"uses weather integration"| node_weather
node_automate -->|"uses seller offers"| node_catalog
node_baproutes -.->|"persists trade data"| node_store

click node_web "https://github.com/kkorel/p2p-trading/blob/main/packages/web/src/app/buy/page.tsx"
click node_chatui "https://github.com/kkorel/p2p-trading/blob/main/packages/web/src/components/chat/chat-page.tsx"
click node_chatapi "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat-routes.ts"
click node_agent "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/agent.ts"
click node_tradingagent "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/trading-agent.ts"
click node_llm "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/llm-fallback.ts"
click node_voice "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/sarvam-stt.ts"
click node_baproutes "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/routes.ts"
click node_sellerroutes "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-routes.ts"
click node_catalog "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-catalog.ts"
click node_orders "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-orders.ts"
click node_callbacks "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/callbacks.ts"
click node_txstate "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/state.ts"
click node_discom "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/discom-mock.ts"
click node_ledger "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/ledger.ts"
click node_auth "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/auth-routes.ts"
click node_middleware "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/middleware/auth.ts"
click node_vc "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/vc/verifier.ts"
click node_solar "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/solar/solar-api.ts"
click node_automate "https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/auto-trade/buyer-agent.ts"
click node_weather "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/weather/weather-service.ts"
click node_store "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/db/prisma.ts"
click node_beckn "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/beckn/secure-client.ts"
click node_trust "https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/trust/trust-engine.ts"

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_web,node_chatui,node_chatapi,node_agent,node_tradingagent,node_llm,node_voice toneBlue
class node_baproutes,node_sellerroutes,node_catalog,node_orders,node_callbacks,node_txstate,node_cds,node_discom,node_ledger toneAmber
class node_auth,node_middleware,node_vc,node_solar,node_automate,node_weather toneMint
class node_store,node_beckn,node_trust toneRose
class node_prosumer toneIndigo
```

## Components

### User experience

- [Trading pages](https://github.com/kkorel/p2p-trading/blob/main/packages/web/src/app/buy/page.tsx): `packages/web/src/app/buy/page.tsx`
- [Oorja interface](https://github.com/kkorel/p2p-trading/blob/main/packages/web/src/components/chat/chat-page.tsx): `packages/web/src/components/chat/chat-page.tsx`
- [Chat routes](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat-routes.ts): `packages/bap/src/chat-routes.ts`
- [Oorja agent](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/agent.ts): `packages/bap/src/chat/agent.ts`
- [Chat trading tools](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/trading-agent.ts): `packages/bap/src/chat/trading-agent.ts`
- [LLM fallback](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/llm-fallback.ts): `packages/bap/src/chat/llm-fallback.ts`
- [Speech services](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/chat/sarvam-stt.ts): `packages/bap/src/chat/sarvam-stt.ts`

### Marketplace trading

- [Buyer API](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/routes.ts): `packages/bap/src/routes.ts`
- [Seller API](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-routes.ts): `packages/bap/src/seller-routes.ts`
- [Seller catalog](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-catalog.ts): `packages/bap/src/seller-catalog.ts`
- [Order handling](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/seller-orders.ts): `packages/bap/src/seller-orders.ts`
- [Buyer callbacks](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/callbacks.ts): `packages/bap/src/callbacks.ts`
- [Transaction state](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/state.ts): `packages/bap/src/state.ts`
- **External catalog**
- [Mock DISCOM](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/discom-mock.ts): `packages/bap/src/discom-mock.ts`
- [Trade ledger](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/ledger.ts): `packages/bap/src/ledger.ts`

### Identity and intelligence

- [Authentication routes](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/auth-routes.ts): `packages/bap/src/auth-routes.ts`
- [Session middleware](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/middleware/auth.ts): `packages/bap/src/middleware/auth.ts`
- [Credential verifier](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/vc/verifier.ts): `packages/shared/src/vc/verifier.ts`
- [Solar analysis](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/solar/solar-api.ts): `packages/shared/src/solar/solar-api.ts`
- [Auto-trade agents](https://github.com/kkorel/p2p-trading/blob/main/packages/bap/src/auto-trade/buyer-agent.ts): `packages/bap/src/auto-trade/buyer-agent.ts`
- [Weather service](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/weather/weather-service.ts): `packages/shared/src/weather/weather-service.ts`

### Shared platform

- [Postgres and Redis](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/db/prisma.ts): `packages/shared/src/db/prisma.ts`
- [Beckn secure client](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/beckn/secure-client.ts): `packages/shared/src/beckn/secure-client.ts`
- [Trust engine](https://github.com/kkorel/p2p-trading/blob/main/packages/shared/src/trust/trust-engine.ts): `packages/shared/src/trust/trust-engine.ts`

### Other components

- **Buyer or seller**

## Connections

- Buyer or seller → Trading pages: uses (evidence: `README.md`)
- Trading pages → Buyer API: calls trading API (evidence: `README.md`)
- Buyer or seller → Oorja interface: uses (evidence: `README.md`)
- Oorja interface → Chat routes: sends chat
- Chat routes → Oorja agent: processes message (evidence: `packages/bap/src/chat-routes.ts`)
- Oorja agent → Chat trading tools: invokes trading tools (evidence: `packages/bap/src/chat/agent.ts`)
- Oorja agent → LLM fallback: requests fallback (evidence: `packages/bap/src/chat/agent.ts`)
- Chat routes → Speech services: transcribes audio (evidence: `packages/bap/src/chat-routes.ts`)
- Buyer API → Transaction state: updates transaction (evidence: `packages/bap/src/routes.ts`)
- Buyer API → External catalog: discovers offers (evidence: `README.md`)
- Buyer API → Beckn secure client: sends Beckn messages
- Seller API → Seller catalog: reads catalog (evidence: `packages/bap/src/seller-routes.ts`)
- Seller API → Order handling: updates order (evidence: `packages/bap/src/seller-routes.ts`)
- Seller API → Transaction state: reads transaction (evidence: `packages/bap/src/seller-routes.ts`)
- Seller API → External catalog: publishes catalog (evidence: `packages/bap/src/seller-routes.ts`)
- Buyer API → Buyer callbacks: receives async response (evidence: `README.md`)
- Seller API → Mock DISCOM: requests delivery check
- Mock DISCOM → Trust engine: informs trust updates (evidence: `README.md`)
- Buyer API → Trade ledger: records confirmed trades (evidence: `README.md`)
- Authentication routes → Session middleware: protects endpoints (evidence: `packages/bap/src/auth-routes.ts`)
- Session middleware → Postgres and Redis: loads user (evidence: `packages/bap/src/middleware/auth.ts`)
- Authentication routes → Postgres and Redis: creates session and reads profile (evidence: `packages/bap/src/auth-routes.ts`)
- Authentication routes → Credential verifier: verifies credentials
- Authentication routes → Solar analysis: requests solar analysis (evidence: `packages/bap/src/auth-routes.ts`)
- Auto-trade agents → Weather service: uses weather integration
- Auto-trade agents → Seller catalog: uses seller offers
- Buyer API → Postgres and Redis: persists trade data