Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (50 loc) · 2.39 KB

AGENTS.md

File metadata and controls

71 lines (50 loc) · 2.39 KB
Raw

AI Agent Instructions for Wingman

Architecture

Slack support assistant with RAG capabilities. Four services in compose.yaml:

  • backend (FastAPI) — REST API at port 8000
  • bot (Slack Bolt) — Socket Mode bot for mentions/DMs
  • frontend (Next.js) — Dashboard at port 3000
  • postgres + chroma — Data storage and vector embeddings

Key: backend and bot share /backend codebase with different entrypoints.

Commands

Use mise run (not make):

mise run install        # uv for backend, bun for frontend
mise run up / down      # Docker services
mise run dev-backend    # Local backend with reload
mise run dev-bot        # Local Slack bot
mise run test-backend   # pytest via uv
mise run shell-db       # psql into postgres

# Database migrations
mise run migrate        # Apply all pending migrations
mise run migrate-down   # Rollback last migration
mise run migrate-history # Show migration history
mise run migrate-current # Show current version

Backend (/backend)

Config: app/config.py — access via from app.config import settings

Singletons (module-level, don't recreate):

  • rag_engine from app.rag
  • vector_store from app.vector_store
  • slack_bot from app.slack_bot

Database: app/database.py — use get_db() as FastAPI dependency

Migrations: Alembic manages schema changes

  • mise run migrate applies pending migrations
  • Create new migrations: MIGRATION_MESSAGE="description" mise run migrate-create (requires running DB)
  • Migration files in backend/migrations/versions/
  • Don't use Base.metadata.create_all() in production — use migrations

API routes in app/main.py: /api/ask, /api/documents, /api/messages

File uploads: Bot automatically indexes files shared in Slack (txt, md, pdf, docx, code files)

Tech Stack:

  • httpx — Async HTTP client for file downloads
  • pypdf + python-docx — PDF and Word document extraction
  • LangChain — RAG orchestration
  • Chroma — Vector embeddings and semantic search
  • SQLAlchemy — ORM with PostgreSQL

Frontend (/frontend)

  • Package manager: Bun
  • App Router in frontend/app/
  • API client at @/lib/api

Environment

Copy .env.example to .env — this is the only environment file needed. Docker uses hostnames (postgres, chroma); local dev uses localhost.

Chroma port: Container 8000 → host 8001