# octopusreview/octopus architecture

> Architecture diagram of the GitHub repository octopusreview/octopus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/octopusreview/octopus
- Repository: https://github.com/octopusreview/octopus

## Overview

Octopus is an AI code-review product for hosted and self-hosted teams, with web, CLI, and local-agent workflows. The primary path is a code-host pull-request event, repository preparation and AI review, then a published review; users can also request reviews from the CLI. Separate capabilities include chat over repository context, dependency-risk analysis, repository knowledge, and integrations. The excerpts establish some calls and analyzer dispatch; README statements support broader product links. Several web subsystems are unsampled, so those links are marked unverified rather than inferred as detailed call chains.

Main entry points: [`apps/web/lib`](https://github.com/octopusreview/octopus/tree/master/apps/web/lib) (Review orchestration), [`apps/cli/src/commands/review.ts`](https://github.com/octopusreview/octopus/blob/master/apps/cli/src/commands/review.ts) (CLI review), [`apps/web/app/api/chat/route.ts`](https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/chat/route.ts) (Repository chat), [`apps/web/lib/review-repository-preparation.ts`](https://github.com/octopusreview/octopus/blob/master/apps/web/lib/review-repository-preparation.ts) (Repository preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI review<br/>[review.ts]"]
  node_cli_api["CLI HTTP client<br/>[api.ts]"]
end

subgraph group_review["Review workflow"]
  node_webhook["GitHub webhook<br/>[route.ts]"]
  node_review_prep["Repository preparation"]
  node_review_engine["Review orchestration"]
  node_review_output["Review results"]
end

subgraph group_intelligence["AI and analysis"]
  node_chat["Repository chat<br/>[route.ts]"]
  node_embeddings["Embeddings<br/>[embeddings.ts]"]
  node_dependency_api["Dependency analysis API<br/>[route.ts]"]
  node_package_analyzer["Package risk analyzer<br/>[index.ts]"]
  node_risk_checks["Risk checks"]
end

subgraph group_platform["Integrations and context"]
  node_knowledge["Knowledge context"]
  node_code_hosts["Code-host integrations"]
  node_forgejo_connector["Forgejo connector<br/>[runner.ts]"]
  node_ai_providers["AI providers"]
end

subgraph group_data["Persistence"]
  node_database[("Application database<br/>[index.ts]")]
end

node_developer(("Developer"))
node_codehost(("Code host"))

node_developer -->|"requests review"| node_cli
node_cli -->|"sends requests"| node_cli_api
node_cli -->|"indexes repository"| node_review_prep
node_cli -.->|"requests review"| node_review_engine
node_codehost -->|"sends events"| node_webhook
node_webhook -->|"starts review"| node_review_engine
node_review_engine -.->|"prepares repository"| node_review_prep
node_review_prep -->|"reads and updates"| node_database
node_review_prep -->|"enqueues review"| node_review_engine
node_review_engine -.->|"publishes findings"| node_review_output
node_developer -.->|"asks question"| node_chat
node_chat -->|"creates vectors"| node_embeddings
node_chat -->|"reads and saves"| node_database
node_chat -.->|"retrieves context"| node_knowledge
node_dependency_api -->|"runs analysis"| node_package_analyzer
node_package_analyzer -->|"dispatches checks"| node_risk_checks
node_developer -.->|"analyzes dependencies"| node_dependency_api
node_review_engine -.->|"requests model review"| node_ai_providers
node_review_engine -.->|"publishes review"| node_code_hosts
node_forgejo_connector -.->|"connects Forgejo"| node_code_hosts

click node_cli "https://github.com/octopusreview/octopus/blob/master/apps/cli/src/commands/review.ts"
click node_cli_api "https://github.com/octopusreview/octopus/blob/master/apps/cli/src/lib/api.ts"
click node_webhook "https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/github/webhook/route.ts"
click node_review_prep "https://github.com/octopusreview/octopus/blob/master/apps/web/lib/review-repository-preparation.ts"
click node_review_engine "https://github.com/octopusreview/octopus/tree/master/apps/web/lib"
click node_review_output "https://github.com/octopusreview/octopus/tree/master/apps/web/lib"
click node_chat "https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/chat/route.ts"
click node_embeddings "https://github.com/octopusreview/octopus/blob/master/apps/web/lib/embeddings.ts"
click node_dependency_api "https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/analyze-deps/route.ts"
click node_package_analyzer "https://github.com/octopusreview/octopus/blob/master/packages/package-analyzer/src/index.ts"
click node_risk_checks "https://github.com/octopusreview/octopus/tree/master/packages/package-analyzer/src"
click node_knowledge "https://github.com/octopusreview/octopus/blob/master/apps/web/lib/knowledge-context.ts"
click node_code_hosts "https://github.com/octopusreview/octopus/tree/master/apps/web/lib"
click node_forgejo_connector "https://github.com/octopusreview/octopus/blob/master/packages/forgejo-connector/src/runner.ts"
click node_ai_providers "https://github.com/octopusreview/octopus/tree/master/apps/web/lib/providers"
click node_database "https://github.com/octopusreview/octopus/blob/master/packages/db/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_api toneBlue
class node_webhook,node_review_prep,node_review_engine,node_review_output toneAmber
class node_chat,node_embeddings,node_dependency_api,node_package_analyzer,node_risk_checks toneMint
class node_knowledge,node_code_hosts,node_forgejo_connector,node_ai_providers toneRose
class node_database,node_developer,node_codehost toneIndigo
```

## Components

### User entry points

- [CLI review](https://github.com/octopusreview/octopus/blob/master/apps/cli/src/commands/review.ts): `apps/cli/src/commands/review.ts`
- [CLI HTTP client](https://github.com/octopusreview/octopus/blob/master/apps/cli/src/lib/api.ts): `apps/cli/src/lib/api.ts`

### Review workflow

- [GitHub webhook](https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/github/webhook/route.ts): `apps/web/app/api/github/webhook/route.ts`
- [Repository preparation](https://github.com/octopusreview/octopus/blob/master/apps/web/lib/review-repository-preparation.ts): `apps/web/lib/review-repository-preparation.ts`
- [Review orchestration](https://github.com/octopusreview/octopus/tree/master/apps/web/lib): `apps/web/lib`
- [Review results](https://github.com/octopusreview/octopus/tree/master/apps/web/lib): `apps/web/lib`

### AI and analysis

- [Repository chat](https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/chat/route.ts): `apps/web/app/api/chat/route.ts`
- [Embeddings](https://github.com/octopusreview/octopus/blob/master/apps/web/lib/embeddings.ts): `apps/web/lib/embeddings.ts`
- [Dependency analysis API](https://github.com/octopusreview/octopus/blob/master/apps/web/app/api/analyze-deps/route.ts): `apps/web/app/api/analyze-deps/route.ts`
- [Package risk analyzer](https://github.com/octopusreview/octopus/blob/master/packages/package-analyzer/src/index.ts): `packages/package-analyzer/src/index.ts`
- [Risk checks](https://github.com/octopusreview/octopus/tree/master/packages/package-analyzer/src): `packages/package-analyzer/src`

### Integrations and context

- [Knowledge context](https://github.com/octopusreview/octopus/blob/master/apps/web/lib/knowledge-context.ts): `apps/web/lib/knowledge-context.ts`
- [Code-host integrations](https://github.com/octopusreview/octopus/tree/master/apps/web/lib): `apps/web/lib`
- [Forgejo connector](https://github.com/octopusreview/octopus/blob/master/packages/forgejo-connector/src/runner.ts): `packages/forgejo-connector/src/runner.ts`
- [AI providers](https://github.com/octopusreview/octopus/tree/master/apps/web/lib/providers): `apps/web/lib/providers`

### Persistence

- [Application database](https://github.com/octopusreview/octopus/blob/master/packages/db/src/index.ts): `packages/db/src/index.ts`

### Other components

- **Developer**
- **Code host**

## Connections

- Developer → CLI review: requests review (evidence: `README.md`)
- CLI review → CLI HTTP client: sends requests (evidence: `apps/cli/src/commands/review.ts`)
- CLI review → Repository preparation: indexes repository (evidence: `apps/cli/src/commands/review.ts`)
- CLI review → Review orchestration: requests review
- Code host → GitHub webhook: sends events (evidence: `README.md`)
- GitHub webhook → Review orchestration: starts review (evidence: `apps/web/app/api/github/webhook/route.ts`)
- Review orchestration → Repository preparation: prepares repository
- Repository preparation → Application database: reads and updates (evidence: `apps/web/lib/review-repository-preparation.ts`)
- Repository preparation → Review orchestration: enqueues review (evidence: `apps/web/lib/review-repository-preparation.ts`)
- Review orchestration → Review results: publishes findings
- Developer → Repository chat: asks question
- Repository chat → Embeddings: creates vectors (evidence: `apps/web/app/api/chat/route.ts`)
- Repository chat → Application database: reads and saves (evidence: `apps/web/app/api/chat/route.ts`)
- Repository chat → Knowledge context: retrieves context
- Dependency analysis API → Package risk analyzer: runs analysis (evidence: `apps/web/app/api/analyze-deps/route.ts`)
- Package risk analyzer → Risk checks: dispatches checks (evidence: `packages/package-analyzer/src/index.ts`)
- Developer → Dependency analysis API: analyzes dependencies
- Review orchestration → AI providers: requests model review
- Review orchestration → Code-host integrations: publishes review
- Forgejo connector → Code-host integrations: connects Forgejo