Spaces:

monireach88
/

smart-chatbot-api

Runtime error

App Files Files Community

smart-chatbot-api / PROJECT.md

GitHub Actions

Deploy from GitHub Actions (2026-05-31 09:04 UTC)

55c0d78 about 1 month ago

preview code

Raw

History Blame Contribute Delete

7.74 kB

Smart Chatbot — Project Navigation

What it is: A chatbot-as-a-service (CaaS) microservice for SMEs. Tenants embed the widget on their site; the chatbot answers domain questions grounded in the tenant's knowledge base (RAG). Sold as prepaid token credits or monthly subscription.

Current Focus

Next: Phase 3 release gate — Simulated Tenant QA Pipeline (all prior gates including Qdrant migration are complete). Full task spec: current_state/project_status.md

Tech Stack

Layer	Technology
Backend	FastAPI, Python, SQLAlchemy, Alembic
Database	PostgreSQL (dev/prod), SQLite (HuggingFace Spaces)
Vector DB	Qdrant — shared collection with required `tenant_id` payload filter; ChromaDB legacy fallback code only
Embeddings	Google Gemini Embedding 2 (`gemini-embedding-2`, 3072-dim)
LLM	LiteLLM Router — provider-agnostic, model aliases in env vars, auto-fallback chains
Frontend	Preact + Shadow DOM widget, Vite build
Auth	API key (widget) + Google OAuth + TOTP 2FA + JWT (admin)
Infra	Docker multi-env, Nginx, Redis/Celery workers, Qdrant, HuggingFace Spaces
CI/CD	GitHub Actions

Project Structure

app/
  routers/      # Route handlers (knowledge_base, system_prompt)
  schemas/      # Pydantic request/response models
  middleware/   # TenantAuthMiddleware (API key → tenant_id)
  models/       # SQLAlchemy models
  services/     # Business logic (EmbeddingService, VectorStore, RetrievalService, LLMService, CreditService, WordPress sync, kb_reindex)
  workers/      # Celery background workers (wordpress_sync, kb_reindex)
  utils/        # api_key, token_counter, seeding
  dependencies/ # FastAPI dependencies (admin_auth)
alembic/        # DB migrations
tests/          # 469 tests, organized by domain
  auth/         # Admin + super-admin auth, JWT, TOTP, OAuth
  knowledge_base/ # KB CRUD, chunking, pagination, reindex, sync
  chat/         # Conversations, RAG context, input limits, history
  billing/      # Credits, billing modes, concurrency
  vector_store/ # Qdrant, ChromaDB, embedding service
  workers/      # Summarization worker, WP sync jobs
  llm/          # LLM service, retrieval, AI verdict, RAG
  infra/        # Middleware, rate limiter, seeding, widget, system prompt
frontend/       # Preact chat widget (Vite build → chatbot-widget.js)
current_state/  # Architecture and status documents (see below)
archive/        # Historical notes and discussion logs (never retroactively edited)
docs/           # Specs and error logs

Key Architecture Decisions

Multi-tenancy: API key → tenant_id extracted in middleware. All DB queries and vector store operations are scoped to tenant_id. Qdrant uses one shared collection with required tenant_id payload filters inside the adapter; PostgreSQL remains the source of truth and Qdrant is a rebuildable search index.

RAG pipeline: /chat → RetrievalService.retrieve(query, tenant_id) → top-k KB docs injected into system message → LLM response grounded in KB.

User auth model: Two modes — anonymous (most SMEs: no end-user login, visitors are anonymous) and authenticated (SaaS/e-commerce: host page passes authenticated user identity). Toggle via admin panel config.

LLM provider abstraction: LLMService wraps LiteLLM Router. Model aliases (chat-model, summarization-model, judge-llm) declared in env vars — swapping providers requires only an env var change, no code change. Auto-fallback chains configured per alias. complete_with_usage() returns LLMResult with token counts for billing.

API versioning: All public endpoints prefixed /api/v1/ — in place before first client embeds widget (one-way door).

Widget embedding: Preact + Shadow DOM — 3KB bundle, fully isolated from host-site CSS/JS, works on any tech stack (WordPress, Vue, React, plain HTML). Admin console generates per-tenant snippet: <script src="widget.js" data-api-key="tenant_abc123"></script>. Widget reads data-api-key at runtime.

Per-tenant customization: All theme/branding/chatbot identity settings stored as customization JSONB on tenants table — zero schema migrations for new settings. Only fields that need filtering (e.g. credits, is_active) get proper columns.

Multi-tenant secrets: Shared secrets (GROQ_API_KEY, DATABASE_URL) live in backend env. Per-tenant config (system prompt, KB, theme) lives in DB. BYOK tenants store their own LLM API key encrypted in customization JSONB.

Credit deduction atomicity: Single SQL UPDATE tenants SET balance_usd = balance_usd - :amount WHERE id = :tenant_id AND balance_usd >= :amount — check rows affected (1 = success, 0 = insufficient balance). No race condition possible without application-level locking.

Key Files

File	Purpose
`app/main.py`	Entry point — router registration, middleware, startup
`app/models/conversation_manager.py`	LLM call lives here — chat logic, context assembly
`app/models/nlp_engine.py`	Analytics and routing only — keep as-is
`app/utils/config.py`	Singleton config — safe to defer refactor
`.env` / `.env.staging` / `.env.production`	Environment-specific values

Business Model

Tier	Best for	How it works
Prepaid credits	Informational sites, low-volume SMEs	Buy credits upfront, deducted per message
Monthly subscription	E-commerce, SaaS, high-volume SMEs	Fixed fee, predictable revenue

Gifted accounts (V1 only): Monireach tops up manually via super-admin; no Stripe needed. Full payment integration is post-V1.

Deployment Roadmap

Stage	Tenants	Stack	Monthly cost
Now	0–10	HuggingFace Spaces (demo/portfolio)	Free
Early	10–100	Railway or Fly.io (managed, zero DevOps)	$10–30
Growth	100–1000	Hetzner VPS + Docker Compose	€10–20
Scale	1000+	Hetzner + K3s (lightweight Kubernetes)	€30–80

Target: Hetzner CAX31 ARM (4 vCPU, 8GB RAM, €14.10/month). PostgreSQL: Supabase managed at small scale → self-hosted at large scale. Admin panels: Cloudflare Pages (free). HF Space kept as public demo proxy only.

K3s local practice (after V1 stable): Deploy the full stack to a local K3s cluster in parallel with Docker Compose — not a replacement for the dev workflow, but a learning environment for writing real K8s manifests (Deployment, Service, Ingress, ConfigMap, Secret) against a real multi-service app. Makes the eventual Hetzner → K3s production migration familiar ground.

Where to Find Things

What you need	File
Task status, V1 checklist, current progress	`current_state/project_status.md`
Full details on completed tasks (sub-tasks, bugs, decisions)	`current_state/milestone.md`
Auth model, tenant isolation, API key design	`docs/security_architecture.md`
Frontend widget architecture, embedding, theming	`docs/frontend_architecture.md`
Khmer language strategy, LLM provider selection	`docs/khmer_llm_strategy.md`
Admin console scope and integration status	`~/projects/smart_chatbot_admin_console/PROJECT.md`
Super-admin console scope and task status	`~/projects/smart_chatbot_super_admin/current_state/project_status.md`
Docker setup, env vars, service topology	`DOCKER_SETUP.md`
Historical discussions (system expansion, billing design)	`archive/`

Live Deployments

Environment	URL
HuggingFace Spaces (public API)	`https://huggingface.co/spaces/monireach88/smart-chatbot-api`
Portfolio (widget embedded)	`https://monireach.com`