# Project Structure

```
├── src/                        # Main application source
│   ├── main.py                 # TSPAssistant facade class (orchestrates all managers)
│   ├── agent_assistant.py      # Agent-enhanced assistant variant
│   ├── agent/                  # ReAct LLM agent
│   │   ├── react_agent.py      # Agent loop with tool dispatch
│   │   └── llm_client.py       # Agent-specific LLM client
│   ├── core/                   # Core infrastructure
│   │   ├── models.py           # SQLAlchemy ORM models (all entities)
│   │   ├── database.py         # DatabaseManager singleton, session management
│   │   ├── llm_client.py       # QwenClient (OpenAI-compatible LLM calls)
│   │   ├── cache_manager.py    # In-memory + Redis caching
│   │   ├── redis_manager.py    # Redis connection pool
│   │   ├── vector_store.py     # Vector storage for embeddings
│   │   ├── embedding_client.py # Local embedding model client
│   │   ├── auth_manager.py     # Authentication logic
│   │   └── ...                 # Performance, backup, query optimizer
│   ├── config/
│   │   └── unified_config.py   # UnifiedConfig singleton (env → dataclasses)
│   ├── dialogue/               # Conversation management
│   │   ├── dialogue_manager.py # Message processing, work order creation
│   │   ├── conversation_history.py
│   │   └── realtime_chat.py    # Real-time chat manager
│   ├── knowledge_base/
│   │   └── knowledge_manager.py # Knowledge CRUD, search, import
│   ├── analytics/              # Monitoring & analytics
│   │   ├── analytics_manager.py
│   │   ├── alert_system.py
│   │   ├── monitor_service.py
│   │   ├── token_monitor.py
│   │   └── ai_success_monitor.py
│   ├── integrations/           # External service integrations
│   │   ├── feishu_client.py    # Feishu API client
│   │   ├── feishu_service.py   # Feishu business logic
│   │   ├── feishu_longconn_service.py  # Feishu event subscription (long-conn)
│   │   ├── workorder_sync.py   # Feishu ↔ local work order sync
│   │   └── flexible_field_mapper.py    # Feishu field mapping
│   ├── vehicle/
│   │   └── vehicle_data_manager.py
│   ├── utils/                  # Shared helpers
│   │   ├── helpers.py
│   │   ├── encoding_helper.py
│   │   └── semantic_similarity.py
│   └── web/                    # Web layer
│       ├── app.py              # Flask app factory, middleware, blueprint registration
│       ├── service_manager.py  # Lazy-loading service singleton registry
│       ├── decorators.py       # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit
│       ├── error_handlers.py   # Unified API response helpers
│       ├── websocket_server.py # Standalone WebSocket server
│       ├── blueprints/         # Flask blueprints (one per domain)
│       │   ├── alerts.py, workorders.py, conversations.py, knowledge.py
│       │   ├── auth.py, tenants.py, chat.py, agent.py, vehicle.py
│       │   ├── analytics.py, monitoring.py, system.py
│       │   ├── feishu_sync.py, feishu_bot.py
│       │   └── test.py, core.py
│       ├── static/             # Frontend assets (JS, CSS)
│       └── templates/          # Jinja2 HTML templates
├── config/                     # Runtime config files (field mappings)
├── data/                       # SQLite DB file, system settings JSON
├── logs/                       # Log files (per-startup subdirectories)
├── scripts/                    # Migration and utility scripts
├── start_dashboard.py          # Main entry point (Flask + WS + Feishu)
├── start_feishu_bot.py         # Standalone Feishu bot entry point
├── init_database.py            # DB initialization script
├── requirements.txt            # Python dependencies
├── nginx.conf                  # Nginx reverse proxy config
└── .env / .env.example         # Environment configuration
```

## Key Patterns

- **Singleton managers**: `db_manager`, `service_manager`, `get_config()` — instantiated once, imported globally.
- **Blueprint-per-domain**: Each functional area (workorders, alerts, knowledge, etc.) has its own Flask blueprint under `src/web/blueprints/`.
- **Service manager with lazy loading**: `ServiceManager` in `src/web/service_manager.py` provides thread-safe lazy initialization of all service instances. Blueprints access services through it.
- **Decorator-driven API patterns**: Common decorators in `src/web/decorators.py` handle error wrapping, JSON validation, tenant resolution, and rate limiting.
- **Multi-tenant by convention**: All DB queries should filter by `tenant_id`. The `@resolve_tenant_id` decorator extracts it from request body, query params, or session.
- **Config from env**: No hardcoded secrets. All configuration flows through `UnifiedConfig` which reads from `.env` via `python-dotenv`.