banban/docs/architecture/01-system-overview.md

System Overview

Runtime Architecture

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