# System Overview

## Runtime Architecture

```mermaid
flowchart LR
  subgraph WeChat["WeChat Ecosystem"]
    Mini["banban-mini\nTaro WeChat mini-program"]
    WxLogin["WeChat login / phone APIs"]
    WxMP["WeChat Official Account\nnotifications and bind"]
  end

  subgraph Edge["Public Edge"]
    Domain["banban.api.talkingq.com"]
    Nginx["Nginx / TLS"]
  end

  subgraph Backend["talkingq-url FastAPI backend"]
    Main["main.py\nFastAPI app + lifespan"]
    AuthMW["banban auth middleware"]
    BanbanRouter["banban routers\nchildren, devices, binding, chat,\nlocation, alarms, firmware, roles,\nwechat-mp"]
    MqttSvc["TalkingQMQTTService"]
    Scheduler["TaskScheduler\ncleanup and periodic tasks"]
    StaticAssets["/assets static files"]
  end

  subgraph Data["Stateful Services"]
    MySQL["MySQL\nshared banban schema"]
    COS["Tencent COS\nmessage audio files"]
    MQTT["MQTT broker"]
  end

  subgraph DeviceSide["Device Side"]
    Device["TalkingQ device"]
    NFC["NFC card"]
  end

  subgraph External["External Providers"]
    MapSvc["Map / reverse geocoding provider"]
    SMS["SMS provider"]
  end

  Mini -->|HTTPS /banban/*| Domain --> Nginx --> Main
  Main --> AuthMW --> BanbanRouter
  Main --> StaticAssets
  Main --> Scheduler
  Main --> MqttSvc
  BanbanRouter --> MySQL
  MqttSvc --> MQTT
  Device -->|device/{id}/event,response| MQTT
  MQTT -->|subscribed messages| MqttSvc
  MqttSvc --> MySQL
  Device --> NFC
  BanbanRouter --> COS
  MqttSvc --> COS
  BanbanRouter --> WxLogin
  BanbanRouter --> WxMP
  BanbanRouter --> SMS
  MqttSvc --> MapSvc
```

## Source Anchors

- Mini-program API base and services: `banban-mini/src/services/*`
- FastAPI startup and router registration: `talkingq-url/main.py`
- Banban route aggregation: `talkingq-url/banban/routers/*`
- MQTT service and device message handlers: `talkingq-url/handlers/mqtt_handler.py`
- Shared database schema: `database/talkingq_shared_schema.sql`
- Runtime database initialization: `talkingq-url/database/init_db.py`