alert-message-center/AGENTS.md

Agent Guide for Alert Message Center

This document provides instructions for AI agents working on the Alert Message Center codebase.

🛠 Commands

Workspace Operations

• Install: bun install
• Root Dev: bun run dev (starts both server and web)
• Root Build: bun run build
• Lint & Format:
  • bun run lint: Run Biome linter
  • bun run format: Fix formatting issues
  • bun run check: Linter + Formatter fix

Backend (apps/server)

• Dev: bun run dev
• Migrations:
  • bun run db:generate: Generate migration files
  • bun run db:push: Push schema changes directly (dev only)
  • bun run db:migrate:deploy: Run migrations in production/Docker
• Verification: bun run src/verify_permissions.ts (Manual verification script)

Frontend (apps/web)

• Dev: bun run dev
• Build: bun run build

Testing

• No automated tests currently exist in the repository. If adding tests, use Bun Test.
• Run Single Test: bun test path/to/file.test.ts

---

📜 Code Style & Conventions

1. General

• Runtime: Bun is the primary runtime. Use node: protocol for built-in modules (e.g., import fs from "node:fs").
• Formatting: Enforced by Biome. Use tabs for indentation and double quotes.
• Naming:
  • Variables/Functions: camelCase
  • Components/Classes/Interfaces: PascalCase
  • Database Tables/Columns: snake_case (e.g., topic_group_chats)
  • URL Slugs: kebab-case

2. TypeScript & Type Safety

• Strict Mode: No any allowed. Use explicit interfaces or Zod schemas.
• Interfaces vs Types: Prefer interface for object definitions and type for unions/aliases.
• RPC: Use hono/client for type-safe communication between frontend and backend.
• Vite Env: Always use optional chaining when accessing import.meta.env?.VITE_....

3. Backend (Hono + Drizzle)

• Routing: Group logic into sub-apps (e.g., api.ts, auth.ts, webhook.ts).
• Database: Use Drizzle ORM. Prefer relational queries where possible (db.query.xxx.findMany).
• Validation: Use @hono/zod-validator for request validation.
• Logging: Use the structured logger in src/lib/logger.ts (Pino).
  • Pattern: logger.error({ err, context }, "Message").

4. Frontend (React + Tailwind)

• Components: Functional components with hooks.
• Styling: Tailwind CSS utility classes. Avoid custom CSS files.
• Icons: Use lucide-react.
• Resilience:
  • Always check res.ok before parsing API responses.
  • Provide fallback states (e.g., []) for data fetching.

5. Error Handling

• Backend: Wrap critical logic in try/catch. Log errors with context. Return meaningful JSON errors with appropriate HTTP status codes.
• Frontend: Use useState to track error states and display user-friendly messages.

---

🏗 Architecture Context

• Topic Model: Alerts are sent to "Topics". Users and Group Chats subscribe to Topics.
• Personal Inbox: Each user has a personalToken (8-character hex) for direct /dm alerts.
• Feishu Integration: Uses @larksuiteoapi/node-sdk. Supports both Webhook and WebSocket modes for events.
• Auth: Feishu SSO (OAuth2). Admin status is assigned via ADMIN_EMAILS env var on first login.

🤖 Rules for Agents

• NO any: This is a hard requirement. Research types or define them.
• Biome First: Always run bun run check before concluding a task.
• Preserve Patterns: Follow existing structure in apps/server/src and apps/web/src.
• Minimalism: Fix bugs minimally. Avoid large refactors unless requested.
• Context: Agent-specific context is located in @docs/. Refer to docs/copilot-context.md for additional instructions.