# overfolder/overslash architecture

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

- Interactive diagram: https://gitdiagram.com/overfolder/overslash
- Repository: https://github.com/overfolder/overslash

## Overview

#### Purpose and entry points
Overslash is a multi-tenant gateway that lets AI agents invoke authenticated external actions without receiving credentials. It combines secrets, OAuth connections, permission inheritance, human approvals, auditing, and HTTP/MCP execution.

Primary runtime entry points:
- Unified CLI/server binary: `crates/overslash-cli/src/main.rs`, with serving modes in `crates/overslash-cli/src/serve.rs` and `crates/overslash-cli/src/web.rs`.
- HTTP API/router: `crates/overslash-api/src/lib.rs` and `crates/overslash-api/src/routes/mod.rs`.
- MCP client/server support: `crates/overslash-mcp/src/lib.rs`, `crates/overslash-api/src/routes/mcp/dispatch.rs`.
- SvelteKit dashboard: `dashboard/src/routes/+layout.svelte`, `dashboard/src/routes/+page.svelte`.

#### API boundary, tenancy, and identity
The Rust/Axum API is the central control plane. Route modules expose management APIs for organizations, identities/agents, groups, credentials, services, approvals, audit records, billing, and events. Authentication supports sessions, magic links, external/OIDC providers, and OAuth authorization-server behavior.

Tenancy and request isolation are enforced at API/database boundaries through subdomain and rate-limit middleware plus scoped repositories:
- `crates/overslash-api/src/middleware/subdomain.rs`
- `crates/overslash-api/src/routes/auth/mod.rs`
- `crates/overslash-db/src/scopes/org.rs`

#### Authorization and approval chain
Permission evaluation models user → agent → subagent chains, applies ceilings and matching rules, and resolves missing authority into approval workflows. Action requests are validated and permission-gated before execution; approvals can be read, resolved, replayed, or auto-called after approval.

Key policy/execution gates:
- `crates/overslash-core/src/permissions/evaluate.rs`
- `crates/overslash-api/src/routes/actions/permission_gate.rs`
- `crates/overslash-api/src/routes/approvals/replay.rs`

This is the core safety boundary: external calls should occur only after identity resolution, permission-chain evaluation, and any required approval.

#### Service definitions and action resolution
Service templates describe third-party APIs, their auth schemes, actions, risks, scopes, and MCP capabilities. YAML registry files are imported/validated into a normalized service model; instances then layer organization-specific configuration, credentials, and discovered tools over templates.

Relevant paths:
- `services/github.yaml`
- `crates/overslash-core/src/openapi/compile.rs`
- `crates/overslash-core/src/template_validation/core/service_shape.rs`
- `crates/overslash-api/src/services/platform_services/reconcile.rs`

Action resolution maps an agent request to an allowed service/action, resolves parameters and secrets, then selects HTTP, platform, or MCP calling paths:
- `crates/overslash-api/src/routes/actions/resolve.rs`
- `crates/overslash-api/src/services/action_caller.rs`
- `crates/overslash-api/src/services/mcp_caller.rs`

#### Credentials, OAuth, and secret handling
Secrets are encrypted and versioned; connections encapsulate OAuth or bring-your-own credentials so agents do not receive raw values. OAuth supports upstream providers, connection initiation/callback flows, incremental scopes, and MCP client authorization.

Important boundaries:
- Crypto and secret injection: `crates/overslash-core/src/crypto.rs`, `crates/overslash-core/src/secret_injection.rs`
- Connection flows: `crates/overslash-api/src/routes/connections/initiate.rs`, `crates/overslash-api/src/routes/connections/callback.rs`
- OAuth AS endpoints: `crates/overslash-api/src/routes/oauth/authorize.rs`, `crates/overslash-api/src/routes/oauth/token.rs`

#### Persistence, audit, and asynchronous signals
PostgreSQL is the system of record for organizations, identities, memberships, permission rules, encrypted secrets, OAuth connections, service instances, execution/approval state, and audit records. SQLx repositories present scoped access rather than allowing routes direct database access.

- Schema evolution: `crates/overslash-db/migrations/001_create_orgs.up.sql`, `crates/overslash-db/migrations/105_events.up.sql`
- Repository layer: `crates/overslash-db/src/repos/mod.rs`
- Auditing/events: `crates/overslash-api/src/services/audit_capture.rs`, `crates/overslash-api/src/services/events/bus.rs`

Events feed live dashboard behavior and approval notifications; webhooks are dispatched separately:
- `crates/overslash-api/src/routes/events.rs`
- `crates/overslash-api/src/services/webhook_dispatcher.rs`

#### Clients and deployment
The dashboard is a separate SvelteKit client consuming API endpoints, with primary operational surfaces for services, connections, secrets, approvals, agents, audit, and organization administration:
- `dashboard/src/lib/api.ts`
- `dashboard/src/routes/services/+page.svelte`
- `dashboard/src/routes/approvals/+page.svelte`

A TypeScript SDK exposes programmatic resources, UI controllers, web components, SSE/event handling, and webhook verification:
- `sdk/src/client.ts`
- `sdk/src/resources/actions.ts`
- `sdk/src/controllers/events.ts`

Production infrastructure is Terraform/OpenTofu targeting Google Cloud: Cloud Run, Cloud SQL/Postgres, Memorystore, load balancing, Secret Manager, Cloud Monitoring, and scheduled metrics export.
- `infra/main.tf`
- `infra/modules/cloud-run/main.tf`
- `infra/modules/cloud-sql/main.tf`

Main entry points: [`crates/overslash-api/src/routes/mod.rs`](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/mod.rs) (Axum API), [`crates/overslash-api/src/routes/actions/resolve.rs`](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/actions/resolve.rs) (Action gate and resolver), [`crates/overslash-api/src/services/events/bus.rs`](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/events/bus.rs) (Audit and event bus), [`crates/overslash-api/src/services/action_caller.rs`](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/action_caller.rs) (Action callers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Gateway runtime"]
  node_cli["CLI and server<br/>Rust entrypoint<br/>[main.rs]"]
end

subgraph group_control["Control plane"]
  node_api["Axum API<br/>control-plane API<br/>[mod.rs]"]
  node_tenant["Tenant isolation<br/>middleware<br/>[subdomain.rs]"]
  node_identity["Identity and OAuth<br/>auth routes<br/>[mod.rs]"]
  node_policy["Permission evaluation<br/>authorization engine<br/>[evaluate.rs]"]
  node_approval["Approval workflow<br/>safety gate<br/>[replay.rs]"]
  node_action_gate["Action gate and resolver<br/>execution orchestration<br/>[resolve.rs]"]
  node_service_registry["Service templates<br/>YAML service registry<br/>[github.yaml]"]
  node_service_instances["Service instances<br/>organization service config<br/>[reconcile.rs]"]
  node_caller["Action callers<br/>HTTP/platform/MCP executor<br/>[action_caller.rs]"]
  node_secrets["Secret protection<br/>crypto and injection"]
end

subgraph group_data["Data and signals"]
  node_repositories["Scoped repositories<br/>SQLx data access<br/>[mod.rs]"]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_audit_events["Audit and event bus<br/>event service<br/>[bus.rs]"]
  node_webhooks["Webhook dispatcher<br/>outbound notifications"]
end

subgraph group_clients["Clients"]
  node_dashboard["SvelteKit dashboard<br/>operations UI<br/>[api.ts]"]
  node_sdk["TypeScript SDK<br/>programmatic client<br/>[client.ts]"]
end

subgraph group_external["External systems"]
  node_providers(("OAuth providers<br/>identity and credential providers"))
  node_third_party(("Third-party services<br/>HTTP and MCP targets"))
  node_gcp{{"Google Cloud deployment<br/>[main.tf]"}}
end

node_cli -->|"serves"| node_api
node_gcp -->|"deploys"| node_cli
node_dashboard -->|"management API"| node_api
node_sdk -->|"programmatic API"| node_api
node_api -->|"applies"| node_tenant
node_tenant -->|"scoped access"| node_repositories
node_api -->|"auth and connections"| node_identity
node_identity -->|"OAuth flows"| node_providers
node_api -->|"action requests"| node_action_gate
node_action_gate -->|"permission check"| node_policy
node_policy -->|"missing authority"| node_approval
node_approval -->|"replay approved action"| node_action_gate
node_action_gate -->|"resolve service"| node_service_instances
node_service_registry -->|"template definitions"| node_service_instances
node_action_gate -->|"authorized invocation"| node_caller
node_secrets -->|"injects credentials"| node_caller
node_caller -->|"HTTP or MCP call"| node_third_party
node_repositories -->|"persists"| node_postgres
node_api -->|"state access"| node_repositories
node_api -->|"audit and signals"| node_audit_events
node_audit_events -->|"live events"| node_dashboard
node_audit_events -->|"dispatch triggers"| node_webhooks

click node_cli "https://github.com/overfolder/overslash/blob/dev/crates/overslash-cli/src/main.rs"
click node_api "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/mod.rs"
click node_tenant "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/middleware/subdomain.rs"
click node_identity "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/auth/mod.rs"
click node_policy "https://github.com/overfolder/overslash/blob/dev/crates/overslash-core/src/permissions/evaluate.rs"
click node_approval "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/approvals/replay.rs"
click node_action_gate "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/actions/resolve.rs"
click node_service_registry "https://github.com/overfolder/overslash/blob/dev/services/github.yaml"
click node_service_instances "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/platform_services/reconcile.rs"
click node_caller "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/action_caller.rs"
click node_secrets "https://github.com/overfolder/overslash/blob/dev/crates/overslash-core/src/secret_injection.rs"
click node_repositories "https://github.com/overfolder/overslash/blob/dev/crates/overslash-db/src/repos/mod.rs"
click node_postgres "https://github.com/overfolder/overslash/blob/dev/crates/overslash-db/migrations/001_create_orgs.up.sql"
click node_audit_events "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/events/bus.rs"
click node_webhooks "https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/webhook_dispatcher.rs"
click node_dashboard "https://github.com/overfolder/overslash/blob/dev/dashboard/src/lib/api.ts"
click node_sdk "https://github.com/overfolder/overslash/blob/dev/sdk/src/client.ts"
click node_gcp "https://github.com/overfolder/overslash/blob/dev/infra/main.tf"

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 toneBlue
class node_api,node_tenant,node_identity,node_policy,node_approval,node_action_gate,node_service_registry,node_service_instances,node_caller,node_secrets toneAmber
class node_repositories,node_postgres,node_audit_events,node_webhooks toneMint
class node_dashboard,node_sdk toneRose
class node_providers,node_third_party,node_gcp toneIndigo
```

## Components

### Gateway runtime

- [CLI and server](https://github.com/overfolder/overslash/blob/dev/crates/overslash-cli/src/main.rs): Rust entrypoint · Runs the gateway serving modes. · `crates/overslash-cli/src/main.rs`

### Control plane

- [Axum API](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/mod.rs): control-plane API · Management, auth, action, and event routes. · `crates/overslash-api/src/routes/mod.rs`
- [Tenant isolation](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/middleware/subdomain.rs): middleware · Subdomain and request tenancy boundary. · `crates/overslash-api/src/middleware/subdomain.rs`
- [Identity and OAuth](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/auth/mod.rs): auth routes · Sessions, external identity, connections, and OAuth authorization. · `crates/overslash-api/src/routes/auth/mod.rs`
- [Permission evaluation](https://github.com/overfolder/overslash/blob/dev/crates/overslash-core/src/permissions/evaluate.rs): authorization engine · Evaluates inherited agent authority and ceilings. · `crates/overslash-core/src/permissions/evaluate.rs`
- [Approval workflow](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/approvals/replay.rs): safety gate · Resolves missing authority and replays approved actions. · `crates/overslash-api/src/routes/approvals/replay.rs`
- [Action gate and resolver](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/routes/actions/resolve.rs): execution orchestration · Validates, authorizes, and resolves requested actions. · `crates/overslash-api/src/routes/actions/resolve.rs`
- [Service templates](https://github.com/overfolder/overslash/blob/dev/services/github.yaml): YAML service registry · Defines third-party actions, auth, risks, and scopes. · `services/github.yaml`
- [Service instances](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/platform_services/reconcile.rs): organization service config · Reconciles templates with organization configuration and tools. · `crates/overslash-api/src/services/platform_services/reconcile.rs`
- [Action callers](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/action_caller.rs): HTTP/platform/MCP executor · Injects resolved credentials and invokes the selected transport. · `crates/overslash-api/src/services/action_caller.rs`
- [Secret protection](https://github.com/overfolder/overslash/blob/dev/crates/overslash-core/src/secret_injection.rs): crypto and injection · Encrypts stored values and injects them only for execution. · `crates/overslash-core/src/secret_injection.rs`

### Data and signals

- [Scoped repositories](https://github.com/overfolder/overslash/blob/dev/crates/overslash-db/src/repos/mod.rs): SQLx data access · Enforces organization-scoped database access. · `crates/overslash-db/src/repos/mod.rs`
- [PostgreSQL](https://github.com/overfolder/overslash/blob/dev/crates/overslash-db/migrations/001_create_orgs.up.sql): system of record · Stores tenancy, identities, policy, connections, state, and audit data. · `crates/overslash-db/migrations/001_create_orgs.up.sql`
- [Audit and event bus](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/events/bus.rs): event service · Captures audit records and emits live operational events. · `crates/overslash-api/src/services/events/bus.rs`
- [Webhook dispatcher](https://github.com/overfolder/overslash/blob/dev/crates/overslash-api/src/services/webhook_dispatcher.rs): outbound notifications · `crates/overslash-api/src/services/webhook_dispatcher.rs`

### Clients

- [SvelteKit dashboard](https://github.com/overfolder/overslash/blob/dev/dashboard/src/lib/api.ts): operations UI · Manages services, connections, approvals, agents, and audit. · `dashboard/src/lib/api.ts`
- [TypeScript SDK](https://github.com/overfolder/overslash/blob/dev/sdk/src/client.ts): programmatic client · Exposes resources, event handling, and webhook verification. · `sdk/src/client.ts`

### External systems

- **OAuth providers**: identity and credential providers
- **Third-party services**: HTTP and MCP targets
- [Google Cloud deployment](https://github.com/overfolder/overslash/blob/dev/infra/main.tf): Cloud Run, Cloud SQL, Redis · `infra/main.tf`

## Connections

- CLI and server → Axum API: serves
- Google Cloud deployment → CLI and server: deploys
- SvelteKit dashboard → Axum API: management API
- TypeScript SDK → Axum API: programmatic API
- Axum API → Tenant isolation: applies
- Tenant isolation → Scoped repositories: scoped access
- Axum API → Identity and OAuth: auth and connections
- Identity and OAuth → OAuth providers: OAuth flows
- Axum API → Action gate and resolver: action requests
- Action gate and resolver → Permission evaluation: permission check
- Permission evaluation → Approval workflow: missing authority
- Approval workflow → Action gate and resolver: replay approved action
- Action gate and resolver → Service instances: resolve service
- Service templates → Service instances: template definitions
- Action gate and resolver → Action callers: authorized invocation
- Secret protection → Action callers: injects credentials
- Action callers → Third-party services: HTTP or MCP call
- Scoped repositories → PostgreSQL: persists
- Axum API → Scoped repositories: state access
- Axum API → Audit and event bus: audit and signals
- Audit and event bus → SvelteKit dashboard: live events
- Audit and event bus → Webhook dispatcher: dispatch triggers