# Tech Stack & Build

## Language & Runtime

- Python 3.11+

## Core Frameworks & Libraries

| Layer | Technology |
|---|---|
| Web framework | Flask 3.x + Flask-CORS |
| ORM / Database | SQLAlchemy 2.x (MySQL via PyMySQL, SQLite for dev) |
| Real-time comms | `websockets` library (standalone server on port 8765) |
| Caching | Redis 5.x client + hiredis |
| LLM integration | OpenAI-compatible API (default provider: Qwen/通义千问 via DashScope) |
| Embedding | `sentence-transformers` with `BAAI/bge-small-zh-v1.5` (local, optional) |
| NLP | jieba (Chinese word segmentation), scikit-learn (TF-IDF) |
| Feishu SDK | `lark-oapi` 1.3.x (event subscription 2.0, long-connection mode) |
| Data validation | pydantic 2.x, marshmallow |
| Auth | JWT (`pyjwt`), SHA-256 password hashing |
| Monitoring | psutil (in-process), Prometheus + Grafana (Docker) |

## Configuration

- All config loaded from environment variables via `python-dotenv` → `src/config/unified_config.py`
- Singleton `UnifiedConfig` with typed dataclasses (`DatabaseConfig`, `LLMConfig`, `ServerConfig`, etc.)
- `.env` file at project root (see `.env.example` for all keys)

## Common Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Initialize / migrate database
python init_database.py

# Start the full application (Flask + WebSocket + Feishu long-conn)
python start_dashboard.py

# Start only the Feishu bot long-connection client
python start_feishu_bot.py

# Run tests
pytest

# Code formatting
black .
isort .

# Linting
flake8
mypy .
```

## Deployment

- Docker + docker-compose (MySQL 8, Redis 7, Nginx, Prometheus, Grafana)
- Nginx reverse proxy in front of Flask (port 80/443 → 5000)
- Default ports: Flask 5000, WebSocket 8765, Redis 6379, MySQL 3306

## Code Quality Tools

- `black` for formatting (PEP 8)
- `isort` for import sorting
- `flake8` for linting
- `mypy` for type checking