Backend – FastAPI¶

File: `API/python/app/app.py`¶

Startup and Configuration¶

The application is loaded with uvicorn via START_CHATBOT_v2.ps1:

$PythonExe -m uvicorn app.app:app --host 127.0.0.1 --port 8000

Environment variables are loaded from the .env file specified by the ENV_PATH environment variable (default: API/chatbot/.env).

Key Variables (from .env)¶

Variable	Description
`GEMINI_API_KEY`	Google Gemini API key
`CACHE_DIR`	Path to JSON cache folder
`LOG_DIR`	Path to log folder
`ALLOWED_TENANT_ID`	⚠️ Hardcoded to `"SKI"` in code

Known limitation

ALLOWED_TENANT_ID = "SKI" is hardcoded at line 20 in app.py. All requests with a different tenant_id are rejected with HTTP 403. This must be removed for full multitenant support.

Endpoints¶

`POST /api/chat`¶

Receives a chat message and returns an AI reply.

Request model:

class ChatRequest(BaseModel):
    tenant_id: str
    message: str
    history: list[dict]  # [{"role": "user"|"assistant", "content": "..."}]

Response model:

{
  "reply": "The driving range is open from 08:00 to 21:00 in summer."
}

Error codes:

Code	Reason
403	`tenant_id` does not match `ALLOWED_TENANT_ID`
404	No cache file found for tenant
500	Gemini error or internal server error

`GET /health`¶

Returns a simple health status:

{"status": "ok", "tenant": "SKI"}

System Prompt¶

build_system_prompt(tenant_id) reads cache/{tenant_id}_context.json and constructs a system message for Gemini containing:

Club name and basic info
Relevant data from all synced tables (news, activities, course info, etc.)
Instruction to reply in the same language as the guest
Instruction to limit answers to club-relevant information

Logging¶

log_interaction(tenant_id, message, reply) writes to {LOG_DIR}/{tenant_id}_chat.jsonl:

{"ts": "2026-05-02T14:23:00Z", "tenant": "SKI", "user": "Hi", "bot": "Hi! How can I help?"}

Logs do not contain IP addresses or personally identifiable information.

File: `API/chatbot/requirements.txt`¶

fastapi==0.116.1
uvicorn[standard]==0.35.0
pyodbc==5.2.0
python-dotenv==1.1.1
google-genai>=1.15.0

File: `API/chatbot/.env.example`¶

The template used to create .env during installation. Never contains real values – see .gitignore.

GEMINI_API_KEY=your-gemini-api-key-here
DB_SERVER=your-sql-server
DB_DATABASE=master
DB_USERNAME=your-db-user
DB_PASSWORD=your-db-password
ODBC_DRIVER=ODBC Driver 17 for SQL Server
CACHE_DIR=C:\ftp\sites\clubsite-4\API\chatbot\cache
LOG_DIR=C:\ftp\sites\clubsite-4\API\chatbot\logs