Architecture.md (12721B)
1 # OpenTel E-Commerce - Architecture Documentation 2 3 ## 1. High-Level System Architecture 4 5 ```mermaid 6 graph TB 7 subgraph Internet["🌐 Internet"] 8 User([👤 User<br/>Web Browser]) 9 end 10 11 subgraph Frontend["Frontend Layer"] 12 SPA[Angular 20 SPA<br/>📱 Single Page Application<br/>━━━━━━━━━━━━━━<br/>• Product Browsing<br/>• Shopping Cart<br/>• Checkout Flow] 13 end 14 15 subgraph Gateway["API Gateway Layer"] 16 BFF[OtelMart Service<br/>🚪 Backend for Frontend<br/>━━━━━━━━━━━━━━<br/>Port: 4200<br/>━━━━━━━━━━━━━━<br/>• Static File Server<br/>• User Authentication<br/>• API Proxy/Router] 17 end 18 19 subgraph Services["Microservices Layer"] 20 PS[Products Service<br/>📦 Product Catalog<br/>━━━━━━━━━━━━━━<br/>Port: 3001<br/>━━━━━━━━━━━━━━<br/>• Catalog Management<br/>• Product Search<br/>• Ratings & Reviews] 21 22 IS[Inventory Service<br/>📊 Stock Management<br/>━━━━━━━━━━━━━━<br/>Port: 3002<br/>━━━━━━━━━━━━━━<br/>• Stock Levels<br/>• Pricing<br/>• Reservations] 23 24 OS[Orders Service<br/>🛒 Order Processing<br/>━━━━━━━━━━━━━━<br/>Port: 3003<br/>━━━━━━━━━━━━━━<br/>• Order Creation<br/>• Payment Processing<br/>• Shipment Tracking] 25 end 26 27 subgraph Data["Data Layer"] 28 DB[(PostgreSQL 17<br/>🗄️ Relational Database<br/>━━━━━━━━━━━━━━<br/>Port: 5433<br/>━━━━━━━━━━━━━━<br/>Schemas:<br/>• users<br/>• products<br/>• inventory<br/>• orders)] 29 end 30 31 User -->|HTTPS| SPA 32 SPA -.->|Bundled & Served| BFF 33 User -->|REST API| BFF 34 35 BFF -->|/api/products/*| PS 36 BFF -->|/api/inventory/*| IS 37 BFF -->|/api/orders/*| OS 38 BFF -->|User Auth| DB 39 40 PS <-->|SQL Queries| DB 41 IS <-->|SQL Queries| DB 42 OS <-->|SQL Queries| DB 43 44 style User fill:#E3F2FD,stroke:#1976D2,stroke-width:3px 45 style SPA fill:#61DAFB,stroke:#20232A,stroke-width:2px,color:#000 46 style BFF fill:#CE422B,stroke:#8B0000,stroke-width:3px,color:#fff 47 style PS fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff 48 style IS fill:#FF9800,stroke:#E65100,stroke-width:2px,color:#fff 49 style OS fill:#2196F3,stroke:#0D47A1,stroke-width:2px,color:#fff 50 style DB fill:#336791,stroke:#1A3A52,stroke-width:3px,color:#fff 51 ``` 52 53 --- 54 55 ## 2. Detailed Service Communication Flow 56 57 ```mermaid 58 sequenceDiagram 59 participant U as 👤 User 60 participant A as Angular SPA 61 participant G as OtelMart Gateway 62 participant P as Products Service 63 participant I as Inventory Service 64 participant O as Orders Service 65 participant D as PostgreSQL 66 67 Note over U,D: User Browse Products Flow 68 69 U->>A: Browse Products 70 A->>G: GET /api/products?page=1 71 G->>P: Proxy → GET /products?page=1 72 P->>D: SELECT FROM products.products 73 D-->>P: Product Data 74 P-->>G: JSON Response 75 G-->>A: Product List 76 A-->>U: Display Products 77 78 Note over U,D: User Place Order Flow 79 80 U->>A: Add to Cart & Checkout 81 A->>G: POST /api/orders (order data) 82 G->>O: Proxy → POST /orders 83 84 O->>I: Check Stock: GET /inventory/{product_id} 85 I->>D: SELECT FROM inventory.stock 86 D-->>I: Stock Data 87 I-->>O: Stock Available 88 89 O->>I: Reserve Stock: POST /inventory/{product_id}/reserve 90 I->>D: UPDATE inventory.stock 91 D-->>I: Updated 92 I-->>O: Reserved 93 94 O->>D: INSERT INTO orders.orders 95 D-->>O: Order Created 96 97 O->>D: INSERT INTO orders.payments 98 D-->>O: Payment Recorded 99 100 O-->>G: Order Success 101 G-->>A: Order Confirmation 102 A-->>U: Show Confirmation Page 103 ``` 104 105 --- 106 107 ## 3. Service Dependencies & Technology Stack 108 109 ```mermaid 110 graph LR 111 subgraph "Tech Stack" 112 direction TB 113 114 subgraph "Frontend" 115 A[Angular 20<br/>TypeScript<br/>Bootstrap 5] 116 end 117 118 subgraph "Backend Services" 119 B[Rust + Axum<br/>Tokio Runtime<br/>Async/Await] 120 end 121 122 subgraph "Database" 123 C[PostgreSQL 17<br/>SQLx Driver<br/>Migrations] 124 end 125 126 subgraph "DevOps" 127 D[Docker + Docker Compose<br/>Multi-stage Builds<br/>Health Checks] 128 end 129 end 130 131 subgraph "Service Dependencies" 132 direction TB 133 O[OtelMart] --> P[Products] 134 O --> I[Inventory] 135 O --> Or[Orders] 136 137 P --> DB[(Database)] 138 I --> DB 139 Or --> DB 140 O --> DB 141 end 142 143 style A fill:#61DAFB,color:#000 144 style B fill:#CE422B,color:#fff 145 style C fill:#336791,color:#fff 146 style D fill:#2496ED,color:#fff 147 ``` 148 149 --- 150 151 ## 4. Database Schema Organization 152 153 ```mermaid 154 graph TB 155 subgraph "PostgreSQL - opentel_db" 156 157 subgraph "users Schema" 158 U1[users<br/>━━━━━━━<br/>id, eid, email<br/>password_hash] 159 U2[user_addresses<br/>━━━━━━━<br/>id, user_id<br/>address details] 160 U3[sessions<br/>━━━━━━━<br/>session_id<br/>user_id, expires_at] 161 162 U1 --- U2 163 U1 --- U3 164 end 165 166 subgraph "products Schema" 167 P1[products<br/>━━━━━━━<br/>id, eid, sku<br/>name, price, stock] 168 P2[product_specifications<br/>━━━━━━━<br/>id, product_id<br/>specifications] 169 P3[customer_reviews<br/>━━━━━━━<br/>id, product_id<br/>rating, review] 170 171 P1 --- P2 172 P1 --- P3 173 end 174 175 subgraph "inventory Schema" 176 I1[inventory_stock<br/>━━━━━━━<br/>id, product_id<br/>quantity, reserved] 177 I2[pricing<br/>━━━━━━━<br/>id, product_id<br/>price, discount] 178 I3[inventory_transactions<br/>━━━━━━━<br/>id, product_id<br/>quantity_change] 179 180 I1 --- I2 181 I1 --- I3 182 end 183 184 subgraph "orders Schema" 185 O1[orders<br/>━━━━━━━<br/>id, eid, order_number<br/>user_id, total] 186 O2[order_items<br/>━━━━━━━<br/>id, order_id<br/>product_id, quantity] 187 O3[payments<br/>━━━━━━━<br/>id, order_id<br/>amount, status] 188 O4[shipments<br/>━━━━━━━<br/>id, order_id<br/>tracking, status] 189 190 O1 --- O2 191 O1 --- O3 192 O1 --- O4 193 end 194 end 195 196 style U1 fill:#9C27B0,color:#fff 197 style U2 fill:#9C27B0,color:#fff 198 style U3 fill:#9C27B0,color:#fff 199 style P1 fill:#4CAF50,color:#fff 200 style P2 fill:#4CAF50,color:#fff 201 style P3 fill:#4CAF50,color:#fff 202 style I1 fill:#FF9800,color:#fff 203 style I2 fill:#FF9800,color:#fff 204 style I3 fill:#FF9800,color:#fff 205 style O1 fill:#2196F3,color:#fff 206 style O2 fill:#2196F3,color:#fff 207 style O3 fill:#2196F3,color:#fff 208 style O4 fill:#2196F3,color:#fff 209 ``` 210 211 --- 212 213 ## 5. Docker Container Architecture 214 215 ```mermaid 216 graph TB 217 subgraph DC["Docker Compose Network: app-network"] 218 219 subgraph "Container: postgres" 220 PG[PostgreSQL 17<br/>━━━━━━━━━━<br/>Volume: postgres_data<br/>Port: 5432→5433<br/>Health Check: pg_isready] 221 end 222 223 subgraph "Container: products-service" 224 PS[Products Service<br/>━━━━━━━━━━<br/>Port: 3001<br/>Env: DATABASE_URL<br/>Runs Migrations] 225 end 226 227 subgraph "Container: inventory-service" 228 IS[Inventory Service<br/>━━━━━━━━━━<br/>Port: 3002<br/>Env: DATABASE_URL<br/>Runs Migrations] 229 end 230 231 subgraph "Container: orders-service" 232 OS[Orders Service<br/>━━━━━━━━━━<br/>Port: 3003<br/>Env: DATABASE_URL<br/>Runs Migrations] 233 end 234 235 subgraph "Container: data-ingestion" 236 DI[Data Ingestion<br/>━━━━━━━━━━<br/>One-time Job<br/>Loads CSV Data<br/>restart: no] 237 end 238 239 subgraph "Container: otelmart" 240 OM[OtelMart<br/>━━━━━━━━━━<br/>Port: 4200<br/>Serves Angular SPA<br/>API Gateway] 241 end 242 end 243 244 PG -.->|Health Check| PS 245 PG -.->|Health Check| IS 246 PG -.->|Health Check| OS 247 PS -.->|Migrations Done| DI 248 DI -.->|Data Loaded| OM 249 250 PS -->|SQL| PG 251 IS -->|SQL| PG 252 OS -->|SQL| PG 253 OM -->|SQL| PG 254 DI -->|SQL| PG 255 256 OM -->|HTTP| PS 257 OM -->|HTTP| IS 258 OM -->|HTTP| OS 259 260 style PG fill:#336791,color:#fff,stroke:#1A3A52,stroke-width:3px 261 style PS fill:#4CAF50,color:#fff,stroke:#2E7D32,stroke-width:2px 262 style IS fill:#FF9800,color:#fff,stroke:#E65100,stroke-width:2px 263 style OS fill:#2196F3,color:#fff,stroke:#0D47A1,stroke-width:2px 264 style DI fill:#9E9E9E,color:#fff,stroke:#424242,stroke-width:2px 265 style OM fill:#CE422B,color:#fff,stroke:#8B0000,stroke-width:3px 266 ``` 267 268 --- 269 270 ## 6. Request Routing Details 271 272 ```mermaid 273 graph LR 274 Browser[🌐 Browser<br/>localhost:4200] 275 276 subgraph OtelMart["OtelMart Service :4200"] 277 Static[Static Files<br/>Angular SPA] 278 Auth[Auth Routes<br/>/api/auth/*] 279 Users[User Routes<br/>/api/users/*] 280 Proxy[API Proxy] 281 end 282 283 subgraph Backend["Backend Microservices"] 284 P[Products<br/>:3001] 285 I[Inventory<br/>:3002] 286 O[Orders<br/>:3003] 287 end 288 289 Browser -->|GET /| Static 290 Browser -->|POST /api/auth/login| Auth 291 Browser -->|GET /api/users/profile| Users 292 Browser -->|GET /api/products| Proxy 293 294 Proxy -->|/api/products/*| P 295 Proxy -->|/api/inventory/*| I 296 Proxy -->|/api/orders/*| O 297 298 style Browser fill:#E3F2FD,stroke:#1976D2,stroke-width:2px 299 style Static fill:#61DAFB,stroke:#20232A,stroke-width:2px,color:#000 300 style Auth fill:#9C27B0,stroke:#4A148C,stroke-width:2px,color:#fff 301 style Users fill:#9C27B0,stroke:#4A148C,stroke-width:2px,color:#fff 302 style Proxy fill:#FF5722,stroke:#BF360C,stroke-width:2px,color:#fff 303 style P fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff 304 style I fill:#FF9800,stroke:#E65100,stroke-width:2px,color:#fff 305 style O fill:#2196F3,stroke:#0D47A1,stroke-width:2px,color:#fff 306 ``` 307 308 --- 309 310 ## Key Architecture Decisions 311 312 ### ✅ **Microservices Benefits** 313 - **Independent Scaling**: Each service can scale independently 314 - **Technology Flexibility**: Each service could use different tech (though all use Rust here) 315 - **Isolated Failures**: One service failure doesn't bring down entire system 316 - **Team Autonomy**: Different teams can own different services 317 318 ### 🏗️ **API Gateway Pattern** 319 - **Single Entry Point**: OtelMart acts as unified API gateway 320 - **Cross-Cutting Concerns**: Authentication, CORS, logging handled centrally 321 - **Backend for Frontend**: Tailored for web client needs 322 - **Service Discovery**: Routes requests to appropriate microservices 323 324 ### 📊 **Database Strategy** 325 - **Logical Separation**: Different schemas per service (users, products, inventory, orders) 326 - **Shared Database**: Simplified for learning (not ideal for production microservices) 327 - **Migration Management**: Each service manages its own schema migrations 328 - **Performance**: Indexes on all foreign keys and common query patterns 329 330 ### 🐳 **Containerization** 331 - **Docker Compose**: Orchestrates all services locally 332 - **Health Checks**: Ensures proper startup order 333 - **Networking**: All services communicate via Docker network 334 - **Volumes**: Persistent database storage 335 336 ### 🔍 **Observability Ready** 337 This architecture is designed for OpenTelemetry instrumentation: 338 - Distributed tracing across service boundaries 339 - Metrics collection from each service 340 - Structured logging with correlation IDs 341 - Context propagation via HTTP headers 342 343 --- 344 345 ## Port Reference 346 347 | Service | Internal Port | External Port | Purpose | 348 |---------|--------------|---------------|---------| 349 | PostgreSQL | 5432 | 5433 | Database connections | 350 | Products | 3001 | 3001 | Product API | 351 | Inventory | 3002 | 3002 | Inventory API | 352 | Orders | 3003 | 3003 | Orders API | 353 | OtelMart | 4200 | 4200 | Web App + Gateway | 354 355 --- 356 357 ## Startup Sequence 358 359 1. **PostgreSQL** starts with health checks 360 2. **Products, Inventory, Orders** services start and run migrations 361 3. **Data Ingestion** loads initial product data (runs once) 362 4. **OtelMart** starts serving Angular app and proxying APIs 363 364 All services wait for PostgreSQL health check before connecting.