Skip to content

AGENTS.md

Latest commit

 

History

History
122 lines (89 loc) · 4.24 KB

AGENTS.md

File metadata and controls

122 lines (89 loc) · 4.24 KB

AI Agent Development Guide

Guidance for agents working in the 508.dev integrations monorepo.

Project Context

This repo contains multiple services:

  • Discord bot (apps/discord_bot)
  • Backend API (apps/api)
  • Worker consumer (apps/worker)
  • Shared package (packages/shared)

Architecture Principles

  1. Feature modularity in bot cogs
  • Bot features live in apps/discord_bot/src/five08/discord_bot/cogs/*.py.
  • Cogs auto-load from the five08.discord_bot.cogs package.
  1. Shared runtime code
  • Cross-service settings/queue/job logic lives in packages/shared/src/five08/.
  • Keep service-specific behavior in each app package.
  1. Service separation
  • apps/discord_bot: Discord gateway and bot commands/cogs
  • apps/api: webhook ingest API and dashboard auth routes
  • apps/worker: queue consumer and processing jobs
  • docker-compose.yml: full container stack for Coolify/local parity; day-to-day dev should prefer host-run app services with Docker-managed infra
  1. Human audit logging
  • Human-triggered CRM actions from Discord should write to the worker audit ingest endpoint.
  • Audit logging must be best effort: command flows should never fail if audit writes fail.
  • Keep reusable audit-write logic outside individual cogs.

Common Paths

  • Bot core: apps/discord_bot/src/five08/discord_bot/bot.py
  • Bot config: apps/discord_bot/src/five08/discord_bot/config.py
  • Bot audit helper: apps/discord_bot/src/five08/discord_bot/utils/audit.py
  • Backend API: apps/api/src/five08/backend/api.py
  • Worker consumer: apps/worker/src/five08/worker/consumer.py
  • Shared settings: packages/shared/src/five08/settings.py
  • Shared queue helpers: packages/shared/src/five08/queue.py

Development Commands

uv sync
./scripts/test.sh
./scripts/lint.sh
./scripts/format.sh
./scripts/mypy.sh

Run services directly:

uv run --package discord_bot discord-bot
uv run --package api backend-api
uv run --package worker worker-consumer

Run the local dev stack:

./scripts/dev.sh infra
./scripts/dev.sh discord-bot
./scripts/dev.sh api
./scripts/dev.sh worker
./scripts/dev.sh all

./scripts/dev.sh is the primary local-dev entrypoint. Full container parity remains available with:

./scripts/docker-compose.sh up --build

Bot Feature Pattern

from discord.ext import commands

class MyCog(commands.Cog):
    def __init__(self, bot: commands.Bot) -> None:
        self.bot = bot

async def setup(bot: commands.Bot) -> None:
    await bot.add_cog(MyCog(bot))

Worker Pattern

  • Keep ingest endpoints fast: validate input, persist jobs, enqueue, return 202.
  • Run long processing in worker consumer jobs (Dramatiq actors), with Postgres as source-of-truth job state and Redis as delivery transport.
  • Internal file movement is routed through MinIO (internal-transfers) inside the stack; this is explicitly the internal transfer path, with external object store adapters kept separate for future needs.
  • Worker schema is managed with Alembic migrations in apps/worker/src/five08/worker/migrations and applied at backend-api startup.

Current Operational Notes (temporary)

  • Protected API auth uses API_SHARED_SECRET for all protected API routes, including webhooks.
  • Worker queue configuration is now resolved to a single effective worker_queue_name; startup fails when WORKER_QUEUE_NAMES contains multiple queue names.
  • Job handler lookup for rerun and worker execution is now centralized in five08.worker.jobs.JOB_FUNCTIONS.

Data Model Note

  • Shared job state is persisted in Postgres table jobs with job type, status (queued, running, succeeded, failed, dead, canceled), payload, idempotency key, attempt counters, scheduling, and lock metadata.

Configuration Rules

  • Add shared env/config in packages/shared/src/five08/settings.py.
  • Add service-specific settings in local service config.py by subclassing shared settings.
  • Keep secrets in env vars, not code.
  • For Discord CRM audit writes, use AUDIT_API_BASE_URL and shared API_SHARED_SECRET.

Agent Guidelines

  • Prefer adding new bot features as isolated cogs.
  • Prefer adding reusable helpers/clients to packages/shared/src/five08/.
  • Update docs and .env.example when introducing new config.
  • Keep changes incremental and testable.