feat: add smart-app-city sub-project architecture

- Architecture globale (React Native + NestJS + FastAPI) - Beckn Protocol (OTN-DPI) integration docs - AI layer: RAG pipeline + AI Agents (LocalAI + Qdrant) - i18n: FR/EN/ES/DE support - Docker Compose for backend services - Project structure with frontend, backend, ai, beckn directories
2026-05-26 18:47:02 -04:00
parent f1e1b98519
commit 94f74f2dfc
20 changed files with 1013 additions and 0 deletions
--- a/smart-app-city/docs/BECKN_INTEGRATION.md
+++ b/smart-app-city/docs/BECKN_INTEGRATION.md
@@ -0,0 +1,113 @@
+# 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