edgedive-monorepo

Edgedive Monorepo

This is the monorepo for all Edgedive applications and supporting packages, including the frontend, backend, and shared libraries.

Quick Start

pnpm install
pnpm run dev

Project Layout

/
├── apps/
│   ├── edgedive-web/     ← Vite + React frontend application
│   └── edgedive-server/  ← Starlette + Uvicorn Python API server
├── packages/
│   ├── typescript-sdk/   ← Generated TypeScript API client from OpenAPI
│   ├── python-sdk/       ← Generated Python SDK (to be configured)
│   └── openapi-schemas/  ← OpenAPI specification files
│       ├── components/
│       │   └── schemas/  ← Schema definition files
│       ├── openapi.yaml  ← Main OpenAPI spec file
│       └── paths/        ← API endpoint definitions
├── pnpm-workspace.yaml   ← PNPM workspace configuration
├── turbo.json            ← Turborepo task configuration
├── package.json          ← Root scripts and devDependencies
├── .gitignore            ← File and folder ignore rules
└── README.md

Prerequisites

• Node.js (v16+ recommended)
• pnpm

  # macOS
  brew install pnpm
  # or globally via npm
  npm install -g pnpm
  

• Python
  • Python 3.12
  • Python 3.10
• ngrok

Setup

Install dependencies

pnpm install

This will automatically:

• Generate API clients for both TypeScript and Python SDKs
• Install all dependencies
• Set up Python environment (including virtual environment and dependencies) via postinstall hook

The SDK generation happens automatically before dependency installation, ensuring fresh client code is available during the installation process.

Client Code Generation

Client code generation happens automatically as part of the pnpm install process, but you can also run it manually:

# Generate all clients
pnpm run gen:clients

# Generate only typescript-sdk
pnpm run gen:clients --filter typescript-sdk

# Clean and regenerate all clients
pnpm run clean:generated && pnpm run gen:clients

The client code is generated from the OpenAPI schemas in packages/openapi-schemas/. The generated code is not committed to git and is regenerated on install.

Processing: Fathom transcripts (June 2025)

• Added fathom to DocumentType and implemented a Fathom transcript processor mirroring Gong. When a tenant has an active Fathom OAuth connection, the orchestrator includes fathom in document chunking. Chunks and interactions use origin_id = recording_id and interaction_type = fathom_meeting.

Note on Filters (June 2025)

• Source filtering now uses documentTypes directly (e.g., intercom_conversation, zendesk_ticket). The previous high-level sourceTypes indirection and SourceType.yaml have been removed. Frontend renders pretty names from document types.

TypeScript SDK

The TypeScript SDK is generated using Orval with React Query integration. Configuration is in packages/typescript-sdk/orval.config.js.

Customer Accounts CSV Upload (June 2025)

• Backend: POST /api/customer-accounts/upload-csv accepts multipart/form-data with file and optional query params defaultCrmSystem (defaults to whatsapp_group) and dryRun (default false). CSV headers must match OpenAPI CrmAccount field names. Unknown columns are captured into the properties JSON.
• Schema: customer_accounts now includes a flexible properties JSONB column (no index by default).
• Frontend: Super Admin Portal includes a "Customer Accounts CSV Upload" card that opens an uploader modal with default CRM system and dry-run options.

Available Scripts

• pnpm run dev
  Runs all dev tasks in parallel via Turborepo (starts frontend & backend dev servers).

• pnpm run install:deps
  Installs Python and Node dependencies (sets up venv, installs pip requirements).

• pnpm run setup:venv
  Creates the Python virtual environment for the backend server.

• pnpm run build
  Builds all projects in topological order and outputs to dist/.

• pnpm run lint
  Runs linting across all workspaces.

• pnpm run test
  Runs tests for all workspaces and reports coverage.

• pnpm run gen:clients
  Generates API clients from OpenAPI schemas in all packages that have a gen:clients script.

• pnpm run clean:generated
  Cleans all generated client code to ensure fresh generation.

Environment Variables

Environment variables for apps should be placed in their respective directories:

• For the web app: apps/edgedive-web/.env
• These .env files are not loaded automatically by Turborepo and need to be loaded by the respective application frameworks (like Vite for the web app)

Ignored Files

Generated client code and other artifacts are ignored via .gitignore:

• Generated client code:
  • packages/typescript-sdk/src/
  • packages/typescript-sdk/dist/
• node_modules/, .pnpm-store/, .turbo/
• Python caches (__pycache__, .venv/, etc.)
• Build outputs (dist/, build/, coverage/)
• Environment files (.env*)
• Editor and OS files (.vscode/, .DS_Store, etc.)

Next Steps

• Configure Python SDK generation in packages/python-sdk/
• Add more services to apps/ directory
• Set up appropriate dependencies between packages
• Update CI workflows to use the Turborepo and pnpm setup

GitHub PR Agent Integration

This repo includes a GitHub PR “chat” integration that lets users mention the agent on a pull request and receive replies directly on the PR.

How It Works

• Sessions are created from Linear (via the Linear AgentSession webhook). When the agent opens or updates a PR, the GitHub Action reports the PR owner/repo/number back to the server, which links the session to that PR number.
• When someone mentions the agent on that PR, the server treats it as a message to the already-linked session, runs the agent (plan/execute), and replies back in the correct PR thread.

Mention Surfaces Supported

• PR Conversation comments (issue_comment)
• PR reviews (pull_request_review submitted)
• Inline PR review comments (pull_request_review_comment created)

Mention syntax: “@ …” (@edgedive, @edgedive-staging, @edgedive-dev)

Webhook Setup

• Endpoint: POST /api/webhook/github
• Signature: HMAC via X-Hub-Signature-256 using GITHUB_WEBHOOK_SECRET
• Events to subscribe to:
  • issue_comment
  • pull_request_review
  • pull_request_review_comment

Environment/Secrets Required

• In GitHub Actions (per environment):
  • GH_APP_ID, GH_PRIVATE_KEY (for installation token and repo access)
  • EDGEDIVE_API_TOKEN (server auth for status/results callbacks)
  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
  • API_SERVER_URL (server base URL)
  • GH_APP_SLUG (for mention detection)
• In server env:
  • GITHUB_WEBHOOK_SECRET (to verify webhooks)
  • GITHUB_APP_ID, GITHUB_PRIVATE_KEY (App auth)

Results Callback Payload

The GitHub Action reports run completion to:

POST /api/agents/agent-sessions/{session_id}/runs/{run_id}/results?tenant_id=<tenant>

Fields (subset shown):

• success (bool), execution_mode ("plan" | "execute")
• commit_sha, pr_url
• pr_owner, pr_repo, pr_number (used to link the session to the PR number deterministically)

Note: Plan runs will not have PR fields; execute runs typically will.

Session Resolution and Replies

• Session resolution uses PR number only: (tenant_id, owner, repo, pull_number)
• No fallback to branch. If a new PR is opened on the same branch, it will not match the old session.
• Reply routing per run:
  • Conversation comment → posts a new PR comment
  • Review comment → replies to the exact inline thread
  • Review → posts a review comment

This ensures precise reply threading and keeps GitHub and Linear in sync while avoiding creating sessions from GitHub.