From e559c86ff32c3a8bbbf4655548a4ee9c29a10816 Mon Sep 17 00:00:00 2001 From: Abhishek Kumar Date: Sat, 27 Dec 2025 08:46:04 +0530 Subject: [PATCH] Add agents.md files --- AGENTS.md | 41 +++++++++++++++++++++++++++ CLAUDE.md | 1 + api/AGENTS.md | 50 +++++++++++++++++++++++++++++++++ api/CLAUDE.md | 1 + docker-compose-local.yaml | 1 - docs/contribution/setup.mdx | 33 +++++++++++++++++++--- scripts/start_services.sh | 2 +- ui/AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++ ui/CLAUDE.md | 1 + 9 files changed, 180 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 api/AGENTS.md create mode 100644 api/CLAUDE.md create mode 100644 ui/AGENTS.md create mode 100644 ui/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e18201e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Dograh - Project Overview + +Dograh is a voice AI platform for building and deploying conversational AI agents with telephony and WebRTC support. + +## Project Structure + +``` +dograh/ +├── api/ # Backend - FastAPI application +├── ui/ # Frontend - Next.js application +├── scripts/ # Helper scripts for local development +├── docs/ # Mintlify documentation +├── pipecat/ # Pipecat framework (git submodule) +├── docker-compose.yaml # Production/OSS deployment +├── docker-compose-local.yaml # Local development services +``` + +## Tech Stack + +- **Backend**: Python with FastAPI +- **Frontend**: Next.js 15 with React 19, TypeScript, Tailwind CSS +- **Database**: PostgreSQL with SQLAlchemy (async) +- **Cache/Queue**: Redis with ARQ for background tasks +- **Storage**: MinIO (S3-compatible) for audio files + +## Local Development + +### Starting Services + +```bash +# Start infrastructure services (postgres, redis, minio) +./scripts/start_services.sh --dev + +# Stop all services +./scripts/stop_services.sh +``` + +## Environment Configuration + +- `api/.env` - Backend environment variables +- `ui/.env` - Frontend environment variables diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/api/AGENTS.md b/api/AGENTS.md new file mode 100644 index 0000000..3db1fa9 --- /dev/null +++ b/api/AGENTS.md @@ -0,0 +1,50 @@ +# API - Backend Service + +FastAPI backend for the Dograh voice AI platform. + +## Project Structure + +``` +api/ +├── app.py # Application entry point, FastAPI setup +├── routes/ # API endpoint handlers +├── services/ # Business logic and integrations +├── db/ # Database models and data access +├── schemas/ # Pydantic request/response schemas +├── tasks/ # Background jobs (ARQ) +├── utils/ # Utility functions +├── alembic/ # Database migrations +├── constants.py # Environment variables and constants +└── tests/ # Test suite +``` + +## Where to Find Things + +| Looking for... | Go to... | +|----------------|----------| +| API endpoints | `routes/` - each file is a router module, aggregated in `routes/main.py` | +| Business logic | `services/` - organized by domain (telephony, workflow, campaign, etc.) | +| Database models | `db/models.py` | +| Database queries | `db/*_client.py` files (repository pattern) | +| Request/response types | `schemas/` | +| Background tasks | `tasks/` - uses ARQ for async job processing | +| Environment config | `constants.py` | + +## API Structure + +- All routes are mounted at `/api/v1` prefix +- Routes are organized by domain (workflow, telephony, campaign, user, etc.) +- `routes/main.py` aggregates all routers + +## Database Migrations + +```bash +./scripts/makemigrate.sh "description" # Create migration +./scripts/migrate.sh # Run migrations +``` + +## Development + +```bash +uvicorn api.app:app --reload --port 8000 +``` diff --git a/api/CLAUDE.md b/api/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/api/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/docker-compose-local.yaml b/docker-compose-local.yaml index 45a83ec..225e751 100644 --- a/docker-compose-local.yaml +++ b/docker-compose-local.yaml @@ -40,7 +40,6 @@ services: minio: image: minio/minio - container_name: minio command: server /data --console-address ":9001" environment: MINIO_ROOT_USER: minioadmin diff --git a/docs/contribution/setup.mdx b/docs/contribution/setup.mdx index c6c7ae8..9c77c9b 100644 --- a/docs/contribution/setup.mdx +++ b/docs/contribution/setup.mdx @@ -34,11 +34,19 @@ nvm use 24 ``` 6. Install UI dependencies ``` -cd ui && npm install +cd ui && npm install && cd .. ``` 7. Start local docker services after making sure you dont have any other instance of postgres or redis running by checking `docker ps` ``` -cd .. && docker compose -f docker-compose-local.yaml up +docker compose -f docker-compose-local.yaml up -d +``` +Verify that the processes have started by running `docker ps` +``` +(dograh) abhishek$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +35b0121f6bd1 minio/minio "/usr/bin/docker-ent…" 6 seconds ago Up 5 seconds (health: starting) 127.0.0.1:9000-9001->9000-9001/tcp dograh-minio-1 +82650ee515ec redis:7 "docker-entrypoint.s…" About a minute ago Up 5 seconds (healthy) 0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp dograh-redis-1 +9636f5d85232 postgres:17 "docker-entrypoint.s…" About a minute ago Up 5 seconds (healthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp dograh-postgres-1 ``` 8. Setup environment variables `` @@ -51,6 +59,23 @@ bash scripts/setup_pipecat.sh 10. Start backend services If you wish to start the services in debug mode, we ship a launch.json file which you can use in VSCode. ``` -bash scripts/start_services.sh +bash scripts/start_services.sh --dev ``` -11. +Verify that your backend server is running +``` +(venv) (dograh) abhishek$ curl -X GET localhost:8000/api/v1/health +{"message":"OK"} +(venv) (dograh) abhishek$ +``` +You would be able to see the logs in logs/ directory. +``` +tail -f logs/latest/*.log +``` +11. Start the UI +``` +cd ui && npm run dev +``` +12. You should be able to open the application on `localhost:3000` now + +### Next Steps +We ship with AGENTS.md and CLAUDE.md which will help the Coding Agents get started quickly with the codebase. This should help your favourite coding agents to be able to navigate the codebase quickly and you can make changes to it and suit your specification better. diff --git a/scripts/start_services.sh b/scripts/start_services.sh index 670109f..a1d9951 100755 --- a/scripts/start_services.sh +++ b/scripts/start_services.sh @@ -51,7 +51,7 @@ BASE_LOG_DIR="$BASE_DIR/logs" # Base logs directory TIMESTAMP=$(date +"%Y%m%d_%H%M%S") LOG_DIR="$BASE_LOG_DIR/$TIMESTAMP" # Timestamped log directory LATEST_LINK="$BASE_LOG_DIR/latest" # Symlink to latest logs -VENV_PATH="$(dirname "$BASE_DIR")/venv" +VENV_PATH="$BASE_DIR/venv" ARQ_WORKERS=${ARQ_WORKERS:-1} diff --git a/ui/AGENTS.md b/ui/AGENTS.md new file mode 100644 index 0000000..3779a75 --- /dev/null +++ b/ui/AGENTS.md @@ -0,0 +1,56 @@ +# UI - Frontend Application + +Next.js 15 frontend for the Dograh voice AI platform. + +## Project Structure + +``` +ui/ +├── src/ +│ ├── app/ # Next.js App Router pages +│ ├── components/ # React components +│ ├── lib/ # Utilities and configurations +│ ├── client/ # Auto-generated API client +│ ├── context/ # React context providers +│ ├── hooks/ # Custom React hooks +│ ├── constants/ # Application constants +│ └── types/ # TypeScript type definitions +├── public/ # Static assets +└── package.json +``` + +## Where to Find Things + +| Looking for... | Go to... | +| ------------------- | ---------------------------------------------------- | +| Pages/routes | `src/app/` - Next.js App Router (file-based routing) | +| Reusable components | `src/components/` - organized by feature | +| Base UI primitives | `src/components/ui/` - shadcn/ui components | +| Workflow builder | `src/components/flow/` - React Flow based | +| API calls | `src/client/` - auto-generated from OpenAPI spec | +| Auth utilities | `src/lib/auth/` | +| Helper functions | `src/lib/utils.ts` | +| Global state | `src/context/` - React context providers | + +## Tech Stack + +- Next.js 15 with App Router, React 19, TypeScript +- Tailwind CSS with shadcn/ui components +- Zustand for state management +- @xyflow/react for workflow builder +- LiveKit for WebRTC voice + +## API Client + +The `src/client/` directory is auto-generated from the backend OpenAPI spec: + +```bash +npm run generate-client +``` + +## Development + +```bash +npm install +npm run dev # Runs on port 3000 +``` diff --git a/ui/CLAUDE.md b/ui/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/ui/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md