# Smart App City — Beckn Protocol (OTN-DPI) Integration

## Overview
Integration with the Beckn Protocol for interoperability with external services (transport, commerce, public services).

## Beckn Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     Beckn Protocol Stack                         │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Mobile App (BAP - Buyer)                │  │
│  │  - Search for services                                    │  │
│  │  - Initiate orders                                        │  │
│  │  - Track fulfillments                                     │  │
│  └───────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                  Beckn Gateway (OTN)                       │  │
│  │  - Routes requests to appropriate BPPs                    │  │
│  │  - Handles subscription management                        │  │
│  │  - Protocol validation                                    │  │
│  └───────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│          ┌───────────────┼───────────────┐                      │
│          ▼               ▼               ▼                      │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐           │
│  │ Transport BPP│ │ Commerce BPP │ │  Admin BPP   │           │
│  │ (Bus, Taxi)  │ │ (Shops)      │ │ (City Hall)  │           │
│  └──────────────┘ └──────────────┘ └──────────────┘           │
└─────────────────────────────────────────────────────────────────┘
```

## Use Cases

### 1. Transport
```json
{
  "context": {
    "action": "search",
    "domain": "mobility:transport:0.8"
  },
  "message": {
    "intent": {
      "fulfillment": {
        "stops": [
          { "location": { "gps": "14.6415,-61.0242" } },
          { "location": { "gps": "14.5900,-60.9800" } }
        ]
      }
    }
  }
}
```

### 2. Commerce Local
```json
{
  "context": {
    "action": "search",
    "domain": "retail:commerce:0.8"
  },
  "message": {
    "intent": {
      "item": { "descriptor": { "name": "Hébergement" } },
      "location": { "city": "Martinique" }
    }
  }
}
```

### 3. Services Publics
```json
{
  "context": {
    "action": "search",
    "domain": "services:govt:0.8"
  },
  "message": {
    "intent": {
      "item": { "descriptor": { "name": "Carte d'identité" } }
    }
  }
}
```

## Integration Points with Smart City

| Beckn Domain | Smart City Component | Data Source |
|--------------|---------------------|-------------|
| mobility:transport | Orion-LD + FROST | Bus GPS, parking sensors |
| retail:commerce | ONDC Adapter | Local business catalog |
| services:govt | City Services API | ERP municipal |
| tourism:experiences | Tourism API | POI database |

## Implementation Plan

### Phase 1: BAP Client
- [ ] Implement Beckn client library in mobile app
- [ ] Connect to OTN Gateway (existing)
- [ ] Basic search functionality

### Phase 2: BPP Adapter
- [ ] Build BPP adapter for city services
- [ ] Connect to transport data (Orion-LD)
- [ ] Connect to commerce directory

### Phase 3: Full Integration
- [ ] Order management
- [ ] Fulfillment tracking
- [ ] Payment integration