From 59894d7dec6be51d9bee975738d4ed65d7bc8795 Mon Sep 17 00:00:00 2001 From: Abhishek Date: Sat, 27 Dec 2025 09:25:20 +0530 Subject: [PATCH] Chore/add setup and contributing docs (#90) * chore: add dev setup documentation * Add agents.md files * simplify contributing documentation --- .gitignore | 5 +- .nvmrc | 1 + .python-version | 1 + AGENTS.md | 41 ++++ CLAUDE.md | 1 + CONTRIBUTING.md | 335 ++--------------------------- README.md | 9 +- api/.env.example | 6 +- api/AGENTS.md | 50 +++++ api/CLAUDE.md | 1 + api/routes/workflow.py | 2 +- docker-compose-local.yaml | 21 ++ docs/contribution/introduction.mdx | 4 + docs/contribution/setup.mdx | 81 +++++++ docs/docs.json | 7 + scripts/start_services.sh | 65 +++++- scripts/stop_services.sh | 146 +++++++++++++ ui/.env.example | 6 + ui/AGENTS.md | 56 +++++ ui/CLAUDE.md | 1 + 20 files changed, 510 insertions(+), 329 deletions(-) create mode 100644 .nvmrc create mode 100644 .python-version 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 docs/contribution/introduction.mdx create mode 100644 docs/contribution/setup.mdx create mode 100755 scripts/stop_services.sh create mode 100644 ui/.env.example create mode 100644 ui/AGENTS.md create mode 100644 ui/CLAUDE.md diff --git a/.gitignore b/.gitignore index 1e4df31..c8acf44 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,7 @@ __pycache__ infrastructure/ nginx/ prd/ -.vercel \ No newline at end of file +.vercel + +venv/ +.venv/ \ No newline at end of file diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..6ac2314 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +v24.11.1 \ No newline at end of file diff --git a/.python-version b/.python-version new file mode 100644 index 0000000..7acdc73 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13.7 \ No newline at end of file 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/CONTRIBUTING.md b/CONTRIBUTING.md index e677d35..631f446 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Dograh AI -Welcome to Dograh AI! 🎉 Thank you for your interest in contributing to the future of open-source voice AI. +Welcome to Dograh AI! ❤️ Thank you for your interest in contributing to the future of open-source voice AI. ❤️ Dograh AI is a comprehensive voice agent platform that helps developers build, test, and deploy conversational AI systems with minimal setup. This guide will help you understand the project structure, set up your development environment, and start contributing effectively. @@ -9,330 +9,42 @@ Dograh AI is a comprehensive voice agent platform that helps developers build, t ## 🏗️ Project Overview ### What is Dograh AI? + Dograh AI is a full-stack platform for building voice agents with a drag-and-drop workflow builder. It combines multiple technologies to provide a seamless experience from development to production deployment. -### Monorepo Architecture -This project uses a monorepo structure with the following main components: - -``` -dograh/ -├── api/ # FastAPI backend service -│ ├── routes/ # API endpoints -│ ├── services/ # Business logic & integrations -│ ├── db/ # Database models & migrations -│ └── requirements.txt # Python dependencies -├── ui/ # Next.js frontend application -│ ├── src/ # React components & pages -│ ├── package.json # Node.js dependencies -│ └── tailwind.config.js # Styling configuration -├── pipecat/ # Voice processing engine (git submodule) -├── scripts/ # Development & deployment scripts -├── docs/ # Documentation -├── docker-compose.yaml # Multi-service orchestration -└── Dockerfile # Container configurations -``` - -### Technology Stack - -**Backend (Python)** -- **Framework**: FastAPI -- **Database**: PostgreSQL with Alembic migrations -- **Cache**: Redis for session management and caching -- **Storage**: S3-compatible storage for audio files and assets (MinIO in OSS mode, AWS S3 in SaaS mode) -- **Voice Engine**: Pipecat integration for real-time voice processing -- **Background Tasks**: ARQ for asynchronous job processing - -**Frontend (TypeScript)** -- **Framework**: Next.js 15 with React 19 -- **UI Components**: Shadcn/ui with Radix UI primitives -- **Styling**: Tailwind CSS with animations -- **State Management**: Zustand for client-side state - -**Infrastructure** -- **Containerization**: Docker with multi-service composition -- **Tunneling**: Cloudflared tunnel for telephony webhook access during development -- **Monitoring**: Sentry for error tracking, Langfuse for LLM observability - -### Deployment Modes - -Dograh AI supports two deployment modes: - -**OSS (Open Source) Mode** -- Self-hosted deployment with local services -- Uses local MinIO for file storage -- Local authentication system -- Full control over data and infrastructure -- Ideal for development and private deployments - -**SaaS (Software as a Service) Mode** -- Cloud-hosted with managed services -- AWS S3 for file storage -- Integrated authentication providers -- Managed infrastructure and scaling -- Production-ready for commercial use - - - ## 🙌 How You Can Contribute -- 🐛 **Report bugs** via GitHub Issues -- 💡 **Suggest features** -- 🔧 **Submit pull requests** -- 📖 **Improve documentation** +- 🐛 **Report bugs** via [GitHub Issues](https://github.com/dograh-hq/dograh/issues) +- 💡 **Suggest features** via [Ideas](https://github.com/orgs/dograh-hq/discussions/categories/ideas) +- 🔧 **Submit pull requests** +- 📖 **Improve documentation** The documentation is hosted via mintlify and the code is in `docs/` folder - 💬 **Join the Slack community** +👉 A great place to start is with issues tagged **`good first issue`**. - -## 🧰 Issue Types - -On our [GitHub Issues page](../../issues), you'll find these templates: - -- 🐛 **Bug Report** - Create a report to help us improve -- 📚 **Documentation Change Request** - Suggest improvements, corrections, or additions to the documentation -- 💡 **Feature Request** - Suggest any ideas you have using our discussion forums -- 🔒 **Report a Security Vulnerability** - Privately report security vulnerabilities to maintainers -- 📝 **Blank issue** - Create a new issue from scratch - -👉 A great place to start is with issues tagged **`good first issue`**. - - - -## 🛠 Development Guidelines - -- Keep PRs focused and scoped -- Follow Python best practices (PEP8) -- **Study existing code structure** before implementing new features - understand patterns, naming conventions, and architectural decisions -- **Follow established patterns** for similar functionality already in the codebase -- Please **link the issue** in your PR description using: `fixes #` - this auto-closes the issue when merged - - +> And if you like the project, but just don't have time to contribute code, that's fine. There are other easy ways to support the project: +> +> - Star the project; +> - Tweet about it; +> - Refer to this project in your project's readme; +> - Submit and vote on [Ideas](https://github.com/orgs/dograh-hq/discussions/categories/ideas); +> - Create and comment on [Issues](https://github.com/dograh-hq/dograh/issues); +> - Mention the project at local meetups and tell your friends/colleagues. ## 🚀 Development Setup -Choose your preferred development approach: - -### Option 1: Docker Development (Recommended for Quick Start) - -The fastest way to get started is using Docker, which provides all services pre-configured: - -```bash -# Clone the repository -git clone https://github.com/dograh-hq/dograh.git -cd dograh - -# Start all services with Docker -docker compose up --pull always -``` - -**Services will be available at:** -- **UI Dashboard**: http://localhost:3010 -- **API Backend**: http://localhost:8000 - -### Option 2: Local Development Setup - -For active development with hot reloading and debugging capabilities: - -#### Prerequisites -- **Python 3.9+** with conda or virtualenv -- **Node.js 18+** and npm -- **PostgreSQL 17** (or use Docker for databases only) -- **Redis 7** (or use Docker for databases only) -- **Git** with submodule support - -#### Backend Development - -1. **Environment Setup** - ```bash - # Create and activate virtual environment - conda create -n dograh python=3.9 - conda activate dograh - # OR using venv: python -m venv venv && source venv/bin/activate - ``` - -2. **Database Services** (if not using local installations) - ```bash - # Start only database services - docker compose up postgres redis minio -d - ``` - -3. **Project Dependencies** - ```bash - # Initialize Pipecat submodule and install dependencies - ./scripts/setup_pipecat.sh - ``` - - This script handles: - - Git submodule initialization for Pipecat voice engine - - Pipecat installation with all required extras (Cartesia, Deepgram, OpenAI, etc.) - - Backend API dependencies installation - -4. **Environment Configuration** - ```bash - # Copy and configure environment variables - cp api/.env.example api/.env - # Edit api/.env with your local database URLs and API keys - ``` - -5. **Launch Backend Services** - ```bash - # Start all backend services with database migrations - ./scripts/start_services.sh - ``` - - This starts: - - FastAPI application (port 8000) - - ARQ background workers - - Campaign orchestrator - - ARI telephony manager - - Automatic database migrations - -#### Frontend Development - -1. **Install Dependencies** - ```bash - cd ui - npm install - ``` - -2. **Code Quality Setup** - ```bash - # Fix any linting issues - npm run fix-lint - ``` - -3. **Start Development Server** - ```bash - # Start with hot reloading - npm run dev - ``` - - Frontend will be available at `http://localhost:3000` - -### Quick Command Reference - -```bash -# Full local development setup -conda activate dograh # Activate Python environment -./scripts/setup_pipecat.sh # Setup voice engine + dependencies -./scripts/start_services.sh # Launch backend services -cd ui && npm install && npm run dev # Start frontend (new terminal) - -# Docker-only development -docker compose up --pull always # Everything in containers -``` - -#### Composite Scripts (Recommended) -These scripts handle multiple tasks automatically: -```bash -./scripts/pre_commit.sh # Format Python + fix frontend linting + restage files -./scripts/start_services.sh # Run migrations + start all backend services -./scripts/setup_pipecat.sh # Initialize submodules + install dependencies -``` - -#### Individual Commands -For specific tasks when you need more control: -```bash -./scripts/migrate.sh # Run database migrations only -./scripts/format.sh # Format Python code only -./pipecat/scripts/fix-ruff.sh # Format Pipecat source code only -cd ui && npm run fix-lint # Fix frontend linting issues -cd ui && npm run lint # Check frontend code quality (no fixes) -``` - -> 💡 **Tip**: Use composite scripts for most development workflows. Individual commands are useful for debugging or working on specific components. - -### Environment Configuration - -Key environment variables (see `api/.env.example` for full list): - -- **Database**: `DATABASE_URL` - PostgreSQL connection string -- **Cache**: `REDIS_URL` - Redis connection for sessions/tasks -- **Storage**: MinIO configuration for audio file storage -- **AI Services**: API keys for OpenAI, Deepgram, ElevenLabs, etc. -- **Telephony**: Twilio or other provider credentials (configured via UI) - - - -## 🔄 Contributing Workflow - -### Getting Started with Your First Contribution - -1. **Fork & Clone** - ```bash - # Fork the repository on GitHub, then clone your fork - git clone https://github.com/YOUR_USERNAME/dograh.git - cd dograh - - # Add upstream remote - git remote add upstream https://github.com/dograh-hq/dograh.git - ``` - -2. **Create Feature Branch** - ```bash - # Create a descriptive branch name - git checkout -b feature/add-voice-detection - git checkout -b fix/authentication-bug - git checkout -b docs/improve-setup-guide - ``` - -3. **Set Up Development Environment** - - Follow the [Development Setup](#-development-setup) guide above - - Test that everything works before making changes - -4. **Make Your Changes** - - Write clean, documented code following existing patterns - - Add tests for new functionality - - Update documentation as needed - -5. **Test Your Changes** - ```bash - # Backend testing - cd api && python -m pytest - - # Frontend linting and building - cd ui && npm run lint && npm run build - ``` - -6. **Commit & Push** - ```bash - git add . - git commit -m "feat: add voice activity detection to improve turn-taking" - git push origin feature/add-voice-detection - ``` - -7. **Open Pull Request** - - Use a descriptive title and link to any related issues - - Include: fixes # to auto-close issues - - Provide context about what your changes do and why - -### Code Standards - -**Python (Backend)** -- Follow PEP 8 style guidelines -- Use type hints for function parameters and return values -- Write docstrings for public functions and classes -- Run `./scripts/pre_commit.sh` before committing (handles both Python formatting and frontend linting) - -**TypeScript (Frontend)** -- Follow existing ESLint configuration -- Use TypeScript strictly (no `any` types) -- Follow existing component patterns and naming conventions -- Run `npm run fix-lint` before committing - -**General Guidelines** -- Keep PRs focused and scoped to one feature/fix -- Write clear commit messages following [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`) -- Update documentation for user-facing changes -- Add tests for new functionality +Please refer to our [Development Setup documentation](https://docs.dograh.com/contribution/setup). ### Getting Help **Before You Start** + - Check existing [GitHub Issues](../../issues) for similar work - Join our [Slack community](https://join.slack.com/t/dograh-community/shared_invite/zt-3czr47sw5-MSg1J0kJ7IMPOCHF~03auQ) to discuss your plans - Look for issues tagged `good first issue` for beginner-friendly tasks **During Development** + - Ask questions in our Slack community - Reference related issues and PRs in your discussions - Share early drafts for feedback on complex features @@ -342,19 +54,10 @@ Key environment variables (see `api/.env.example` for full list): Our Slack community is the heart of Dograh AI development: - **Get Help**: Setup assistance and debugging support -- **Collaborate**: Discuss features and architectural decisions +- **Collaborate**: Discuss features and architectural decisions - **Connect**: Meet other contributors and maintainers - **Stay Updated**: Learn about contribution opportunities and releases 👉 **Join us**: [Dograh Community Slack](https://join.slack.com/t/dograh-community/shared_invite/zt-3czr47sw5-MSg1J0kJ7IMPOCHF~03auQ) -### Other Ways to Contribute - -Beyond code, you can help by: -- **Reporting bugs** with detailed reproduction steps -- **Suggesting features** that solve real problems -- **Improving documentation** and examples -- **Testing releases** and providing feedback -- **Helping other community members** in Slack - Thank you for helping us keep voice AI open and accessible! 🎉 diff --git a/README.md b/README.md index 916ef91..4764fba 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,9 @@ Docs: https://docs.dograh.com + + Deepwiki: https://deepwiki.com/dograh-hq/dograh + License: BSD 2-Clause @@ -35,8 +38,6 @@ ## 🚀 Get Started -The only command you need to run: - ##### Download and setup Dograh on your Local Machine > **Note** @@ -78,7 +79,7 @@ curl -o docker-compose.yaml https://raw.githubusercontent.com/dograh-hq/dograh/m ### Voice Capabilities -- Telephony: Built-in Twilio integration (easily add others) +- Telephony: Built-in telephony integration like Twilio, Vonage, Vobiz, Cloudonix (easily add others) - Languages: English support (expandable to other languages) - Custom Models: Bring your own TTS/STT models - Real-time Processing: Low-latency voice interactions @@ -104,7 +105,7 @@ Architecture diagram _(coming soon)_ ### Local Development -Refer [prerequisites](https://docs.dograh.com/getting-started/prerequisites) and [first steps](#-get-started) +Refer [Local Setup](https://docs.dograh.com/contribution/setup) ### Self-Hosted Deployment diff --git a/api/.env.example b/api/.env.example index c9451a4..39d9040 100644 --- a/api/.env.example +++ b/api/.env.example @@ -5,14 +5,14 @@ LOG_LEVEL="DEBUG" # Change these values if you deploy the backend and frontend # on any hosting provider with some DNS. Please ensure to # provide the URL with scheme like http or https -# BACKEND_API_ENDPOINT: "http://localhost:8000" -# UI_APP_URL: "http://localhost:3010" +BACKEND_API_ENDPOINT="http://localhost:8000" +UI_APP_URL="http://localhost:3000" # Database Configuration DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/postgres" REDIS_URL="redis://:redissecret@localhost:6379" -# AWS S3 Configuration (required for SaaS mode) +# AWS S3 Configuration ENABLE_AWS_S3="false" # AWS_ACCESS_KEY_ID="" # AWS_SECRET_ACCESS_KEY="" 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/api/routes/workflow.py b/api/routes/workflow.py index 0a05ee2..e6ebde9 100644 --- a/api/routes/workflow.py +++ b/api/routes/workflow.py @@ -600,7 +600,7 @@ async def get_workflow_run( "call_duration_seconds": int( round(run.cost_info.get("call_duration_seconds")) ) - if run.cost_info + if run.cost_info and run.cost_info.get("call_duration_seconds") is not None else None, } if run.cost_info diff --git a/docker-compose-local.yaml b/docker-compose-local.yaml index 1145451..225e751 100644 --- a/docker-compose-local.yaml +++ b/docker-compose-local.yaml @@ -38,9 +38,30 @@ services: networks: - app-network + minio: + image: minio/minio + command: server /data --console-address ":9001" + environment: + MINIO_ROOT_USER: minioadmin + MINIO_ROOT_PASSWORD: minioadmin + MINIO_API_CORS_ALLOW_ORIGIN: "*" + ports: + - "127.0.0.1:9000:9000" # Bind to localhost explicitly + - "127.0.0.1:9001:9001" + volumes: + - minio_data:/data + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"] + interval: 10s + timeout: 5s + retries: 5 + networks: + - app-network + volumes: postgres_data: redis_data: + minio_data: networks: app-network: diff --git a/docs/contribution/introduction.mdx b/docs/contribution/introduction.mdx new file mode 100644 index 0000000..0c8b45b --- /dev/null +++ b/docs/contribution/introduction.mdx @@ -0,0 +1,4 @@ +--- +title: Contribution +description: If you would like to set up the development environment and use a coding agent like Claude to make changes to the codebase, you can follow this document to help setup the right development environment for yourself. +--- \ No newline at end of file diff --git a/docs/contribution/setup.mdx b/docs/contribution/setup.mdx new file mode 100644 index 0000000..b638ae4 --- /dev/null +++ b/docs/contribution/setup.mdx @@ -0,0 +1,81 @@ +--- +title: Setup +description: You can use this document to setup the dev environment for yourself. +--- + +If the below steps do not work out for you, it would be great if you can open an issue on [Github](https://github.com/dograh-hq/dograh/issues). + + +### System Requirements +- git to clone the forked repository +- Node.js 24 to run the UI (we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage your node versions locally) +- Python 3.13 to run the backend +- Docker to run the database and redis cache locally + +### Steps +1. Fork the Dograh repository by going to https://github.com/dograh-hq/dograh +2. Clone the forked repository on your machine +``` +git clone https://github.com//dograh +cd dograh +``` +3. Create a python virtual environment +``` +python3 -m venv venv +source venv/bin/activate +``` +4. Install the requirements +``` +pip install -r api/requirements.txt +``` +5. Ensure you are on right version of Node.js using `node --version` +``` +nvm use 24 +``` +6. Install UI dependencies +``` +cd ui && npm install && cd .. +``` +7. Start local docker services +Please ensure you dont have any other instance of conflicting services running by checking `docker ps` +``` +docker compose -f docker-compose-local.yaml up -d +``` +Verify that the processes have started by running `docker ps` +``` +abhishek$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9066b7244b2f postgres:17 "docker-entrypoint.s…" 18 seconds ago Up 18 seconds (healthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp dograh-postgres-1 +6c7cb8afdf18 redis:7 "docker-entrypoint.s…" 18 seconds ago Up 18 seconds (healthy) 0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp dograh-redis-1 +a57e3e92b02c minio/minio "/usr/bin/docker-ent…" 18 seconds ago Up 18 seconds (healthy) 127.0.0.1:9000-9001->9000-9001/tcp dograh-minio-1 +``` +8. Setup environment variables +`` +cp api/.env.example api/.env && cp ui/.env.example ui/.env +`` +9. Setup pipecat git submodule +``` +bash scripts/setup_pipecat.sh +``` +10. Start backend services +``` +bash scripts/start_services.sh --dev +``` +Verify that your backend server is running +``` +(venv)abhishek$ curl -X GET localhost:8000/api/v1/health +{"message":"OK"} +(venv)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/docs/docs.json b/docs/docs.json index b9ff93a..e005bcd 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -54,6 +54,13 @@ } ] }, + { + "group": "Contribution", + "pages": [ + "contribution/introduction", + "contribution/setup" + ] + }, { "group": "Deployment", "pages": [ diff --git a/scripts/start_services.sh b/scripts/start_services.sh index 98d7239..a1d9951 100755 --- a/scripts/start_services.sh +++ b/scripts/start_services.sh @@ -1,6 +1,42 @@ #!/usr/bin/env bash set -e # Exit on error +############################################################################### +### ARGUMENT PARSING +############################################################################### + +DEV_MODE=false + +show_help() { + echo "Usage: $0 [OPTIONS]" + echo "" + echo "Options:" + echo " --dev Enable development mode with auto-reload for API changes" + echo " --help Show this help message" + echo "" + echo "Examples:" + echo " $0 # Start in production mode" + echo " $0 --dev # Start in development mode with auto-reload" +} + +while [[ $# -gt 0 ]]; do + case $1 in + --dev) + DEV_MODE=true + shift + ;; + --help|-h) + show_help + exit 0 + ;; + *) + echo "Unknown option: $1" + show_help + exit 1 + ;; + esac +done + ############################################################################### ### CONFIGURATION ############################################################################### @@ -15,13 +51,18 @@ 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} # Log startup cd "$BASE_DIR" -echo "Starting Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}" +if $DEV_MODE; then + echo "Starting Dograh Services (DEV MODE) at $(date) in BASE_DIR: ${BASE_DIR}" + echo "Auto-reload enabled for api/ directory changes" +else + echo "Starting Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}" +fi ############################################################################### ### 1) Load environment variables @@ -47,10 +88,19 @@ SERVICE_NAMES=( "uvicorn" ) +# Build uvicorn command based on mode +if $DEV_MODE; then + # Dev mode: single worker with auto-reload (--reload is incompatible with --workers > 1) + UVICORN_CMD="uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --reload --reload-dir api" +else + # Production mode: multiple workers, no reload + UVICORN_CMD="uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --workers $FASTAPI_WORKERS" +fi + SERVICE_COMMANDS=( "python -m api.services.telephony.ari_manager" "python -m api.services.campaign.campaign_orchestrator" - "uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --workers $FASTAPI_WORKERS" + "$UVICORN_CMD" ) # Add ARQ workers dynamically @@ -208,14 +258,21 @@ done echo echo "──────────────────────────────────────────────────" +if $DEV_MODE; then + echo "Mode: DEVELOPMENT (auto-reload enabled)" +else + echo "Mode: PRODUCTION" +fi +echo "" for name in "${SERVICE_NAMES[@]}"; do pid=$(<"$RUN_DIR/$name.pid") echo "✓ $name (PID $pid) → $LOG_DIR/$name.log" done +echo "" echo " Rotation: ${LOG_ROTATION_SIZE:-100 MB}" echo " Retention: ${LOG_RETENTION:-7 days}" echo " Compression: ${LOG_COMPRESSION:-gz}" echo "Logs: tail -f $LOG_DIR/*.log" echo "Rotated logs: ls $LOG_DIR/*.log.*" -echo "To stop: run this script again or kill -TERM - for process groups" +echo "To stop: ./scripts/stop_services.sh" echo "──────────────────────────────────────────────────" diff --git a/scripts/stop_services.sh b/scripts/stop_services.sh new file mode 100755 index 0000000..887e1aa --- /dev/null +++ b/scripts/stop_services.sh @@ -0,0 +1,146 @@ +#!/usr/bin/env bash +set -e # Exit on error + +############################################################################### +### CONFIGURATION +############################################################################### + +# Determine BASE_DIR as parent of the scripts directory +BASE_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)" + +RUN_DIR="$BASE_DIR/run" # Where we keep *.pid + +cd "$BASE_DIR" +echo "Stopping Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}" + +############################################################################### +### HELPER FUNCTIONS +############################################################################### + +# Function to get all descendant PIDs of a process (children, grandchildren, etc.) +get_descendants() { + local parent_pid=$1 + local descendants="" + local children + + # Get direct children + children=$(pgrep -P "$parent_pid" 2>/dev/null || true) + + for child in $children; do + # Recursively get descendants of each child + descendants="$descendants $child $(get_descendants "$child")" + done + + echo "$descendants" +} + +# Function to kill a process and all its descendants +kill_process_tree() { + local pid=$1 + local signal=$2 + local descendants + + descendants=$(get_descendants "$pid") + + # Kill children first (bottom-up), then parent + for desc_pid in $descendants; do + if kill -0 "$desc_pid" 2>/dev/null; then + kill "$signal" "$desc_pid" 2>/dev/null || true + fi + done + + # Kill the parent + if kill -0 "$pid" 2>/dev/null; then + kill "$signal" "$pid" 2>/dev/null || true + fi +} + +############################################################################### +### STOP SERVICES +############################################################################### + +if [[ ! -d "$RUN_DIR" ]]; then + echo "No run directory found at $RUN_DIR" + echo "No services appear to be running." + exit 0 +fi + +# Find all PID files in the run directory +pid_files=("$RUN_DIR"/*.pid) + +# Check if any PID files exist +if [[ ! -e "${pid_files[0]}" ]]; then + echo "No PID files found in $RUN_DIR" + echo "No services appear to be running." + exit 0 +fi + +stopped_count=0 +failed_count=0 + +for pidfile in "${pid_files[@]}"; do + # Extract service name from pidfile path + name=$(basename "$pidfile" .pid) + + if [[ -f "$pidfile" ]]; then + oldpid=$(<"$pidfile") + + if kill -0 "$oldpid" 2>/dev/null; then + echo "Stopping $name (PID $oldpid and all descendants)..." + + # Kill the entire process tree (parent + all descendants) + kill_process_tree "$oldpid" "-TERM" + sleep 4 + + # Check if parent or any descendants are still alive + still_alive=false + if kill -0 "$oldpid" 2>/dev/null; then + still_alive=true + else + for desc_pid in $(get_descendants "$oldpid"); do + if kill -0 "$desc_pid" 2>/dev/null; then + still_alive=true + break + fi + done + fi + + if $still_alive; then + echo " Warning: $name did not exit cleanly, forcing stop..." + kill_process_tree "$oldpid" "-KILL" + sleep 1 + + # Final check + if kill -0 "$oldpid" 2>/dev/null; then + echo " Error: Failed to stop $name (PID $oldpid)" + ((failed_count++)) + else + echo " Stopped $name (forced)" + ((stopped_count++)) + fi + else + echo " Stopped $name" + ((stopped_count++)) + fi + else + echo "Service $name (PID $oldpid) is not running" + fi + + rm -f "$pidfile" + fi +done + +# Clean up any port tracking files for uvicorn +rm -f "$RUN_DIR/uvicorn.port" "$RUN_DIR/uvicorn_new.port" "$RUN_DIR/uvicorn_old.pid" + +############################################################################### +### SUMMARY +############################################################################### + +echo +echo "──────────────────────────────────────────────────" +echo "Stopped $stopped_count service(s)" +if [[ $failed_count -gt 0 ]]; then + echo "Failed to stop $failed_count service(s)" +fi +echo "──────────────────────────────────────────────────" diff --git a/ui/.env.example b/ui/.env.example new file mode 100644 index 0000000..284108b --- /dev/null +++ b/ui/.env.example @@ -0,0 +1,6 @@ +NEXT_PUBLIC_BACKEND_URL=http://localhost:8000 +BACKEND_URL=http://localhost:8000 + +NEXT_PUBLIC_NODE_ENV=development +NEXT_PUBLIC_DEPLOYMENT_MODE: "oss" +NEXT_PUBLIC_AUTH_PROVIDER="local" 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