# kushagrasaxena28/crator-assignment architecture

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

- Interactive diagram: https://gitdiagram.com/kushagrasaxena28/crator-assignment
- Repository: https://github.com/kushagrasaxena28/crator-assignment

## Overview

#### Purpose and topology
This repository implements a local permissions, approval, and audit gateway for AI-agent calls to external services. It has two independently run Python processes: a Django/DRF backend and a Claude Agent SDK CLI. The CLI intentionally routes external operations through backend HTTP endpoints, making the backend the enforcement boundary.

- Backend entry points: `backend/manage.py`, `backend/config/urls.py`, `backend/config/settings.py`
- Agent entry points: `agent-cli/agent_cli_script/__main__.py`, `agent-cli/agent_cli_script/session.py`

#### Backend API and trust boundary
Django exposes token issuance plus `/api/external-services/` APIs for toolkit discovery, schemas, action calls, approval polling/resolution, permission administration, and audit queries. JWT authentication identifies agents for normal calls; Basic auth protects human-only approval and permission-management operations.

- Routing/configuration: `backend/config/urls.py`, `backend/external_services/urls.py`
- Auth/token enforcement: `backend/external_services/authentication.py`, `backend/external_services/tokens.py`
- Endpoint handlers: `backend/external_services/views/toolkits.py`, `backend/external_services/views/approvals.py`, `backend/external_services/views/permissions.py`

#### Permission and validation pipeline
An action call resolves the caller’s effective policy from a sparse `(agent, action)` override, otherwise using the cataloged action default. Policies branch into immediate execution, approval-ticket creation, or denial. Request parameters are checked against the action’s persisted JSON schema before execution, preventing separate runtime validators from drifting.

- Core policy: `backend/external_services/permissions.py`
- Persistent domain/schema: `backend/external_services/models.py`
- Validation: `backend/external_services/validation.py`

#### Approval and immutable audit flow
Approval-required calls return a ticket and create a `pending_approval` audit event. A human resolves the ticket; resolution executes or rejects the action and emits a separate terminal audit event. Expiration is handled lazily during ticket reads/resolution. Audit identity is snapshot-based rather than an agent foreign key, preserving history after agent deletion.

- Approval API: `backend/external_services/views/approvals.py`
- Audit write/mirroring path: `backend/external_services/audit.py`
- Models/admin controls: `backend/external_services/models.py`, `backend/external_services/admin.py`

#### Toolkit abstraction and external boundaries
Toolkit-aware code is isolated from the generic auth, permissions, approvals, and audit pipeline. Catalogs define actions and defaults; a registry dispatches to toolkit executors. `items` and `github` mutate process-local in-memory stores, while Notion uses its live REST API and environment-provided credentials.

- Registry/dispatch: `backend/external_services/toolkits/__init__.py`
- Mock toolkit example: `backend/external_services/toolkits/items/catalog.py`, `backend/external_services/toolkits/items/executors.py`, `backend/external_services/toolkits/items/store.py`
- Live integration: `backend/external_services/toolkits/notion/client.py`, `backend/external_services/toolkits/notion/executors.py`

#### Provisioning and persistence
SQLite persists only gateway metadata: agents, toolkit/action catalog, sparse overrides, tickets, and audit history. The idempotent seed command provisions the demo agent and action catalog. Django ORM is the persistence boundary, so database replacement is configuration-led.

- Schema/migrations: `backend/external_services/models.py`, `backend/external_services/migrations/0001_initial.py`
- Catalog provisioning: `backend/external_services/management/commands/seed.py`
- Runtime settings: `backend/config/settings.py`

#### Agent CLI control flow
The CLI hosts an interactive Claude session. Its sole custom tool obtains JWTs; session code caches and refreshes them. The model uses Bash/curl to invoke backend APIs, while a background watcher independently polls pending ticket statuses and emits approval notifications. It requires Anthropic’s API; the backend itself does not.

- CLI/session orchestration: `agent-cli/agent_cli_script/__main__.py`, `agent-cli/agent_cli_script/session.py`
- Model instructions and JWT tool: `agent-cli/agent_cli_script/system_prompt.py`, `agent-cli/agent_cli_script/tools/generate_jwt.py`
- Async approval notifications: `agent-cli/agent_cli_script/ticket_watcher.py`

Main entry points: [`agent-cli/agent_cli_script/session.py`](https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/session.py) (Claude session), [`backend/external_services/views/toolkits.py`](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/views/toolkits.py) (API handlers), [`backend/external_services/permissions.py`](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/permissions.py) (Policy & schema validation), [`backend/external_services/urls.py`](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/urls.py) (Gateway API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Django Gateway"]
  node_django_entry["Django app<br/>backend entrypoint<br/>[manage.py]"]
  node_api_router["Gateway API routes<br/>Django routing<br/>[urls.py]"]
  node_api_handlers["API handlers<br/>DRF views<br/>[toolkits.py]"]
  node_auth_tokens["JWT &amp; Basic auth<br/>authentication<br/>[authentication.py]"]
  node_policy_validation["Policy &amp; schema validation<br/>authorization pipeline<br/>[permissions.py]"]
  node_approval_audit["Approvals &amp; audit<br/>workflow service<br/>[audit.py]"]
  node_toolkit_registry["Toolkit registry<br/>executor dispatch<br/>[__init__.py]"]
  node_gateway_models[("Gateway domain models<br/>Django ORM<br/>[models.py]")]
  node_sqlite[("SQLite metadata<br/>database")]
  node_seed_catalog["Catalog seed command<br/>provisioning command<br/>[seed.py]"]
  node_mock_toolkits["Items/GitHub mock toolkits<br/>in-memory executors<br/>[executors.py]"]
  node_notion_toolkit["Notion toolkit<br/>live REST executor<br/>[executors.py]"]
end

subgraph group_cli["Agent CLI"]
  node_cli_entry["CLI entrypoint<br/>Python CLI<br/>[__main__.py]"]
  node_cli_session["Claude session<br/>session orchestration<br/>[session.py]"]
  node_cli_prompt_tool["Instructions &amp; JWT tool<br/>model tool<br/>[generate_jwt.py]"]
  node_ticket_watcher["Ticket watcher<br/>async poller<br/>[ticket_watcher.py]"]
end

subgraph group_external["External Systems"]
  node_anthropic{{"Anthropic API<br/>model API"}}
  node_notion_api{{"Notion REST API<br/>external service"}}
end

node_cli_entry -->|"starts"| node_cli_session
node_cli_session -->|"provides tool"| node_cli_prompt_tool
node_cli_session -->|"runs watcher"| node_ticket_watcher
node_cli_session -->|"interactive session"| node_anthropic
node_cli_session -->|"Bash/curl API calls"| node_api_router
node_ticket_watcher -.->|"polls tickets"| node_api_router
node_django_entry -->|"serves"| node_api_router
node_api_router -->|"routes requests"| node_api_handlers
node_api_handlers -->|"authenticates"| node_auth_tokens
node_api_handlers -->|"authorizes action calls"| node_policy_validation
node_policy_validation -->|"reads policy and schema"| node_gateway_models
node_policy_validation -->|"creates approval or audit outcome"| node_approval_audit
node_policy_validation -->|"dispatches allowed actions"| node_toolkit_registry
node_api_handlers -->|"resolves and queries tickets"| node_approval_audit
node_approval_audit -->|"persists tickets and events"| node_gateway_models
node_gateway_models -->|"ORM persistence"| node_sqlite
node_seed_catalog -->|"provisions catalog"| node_gateway_models
node_toolkit_registry -->|"dispatches mock actions"| node_mock_toolkits
node_toolkit_registry -->|"dispatches live actions"| node_notion_toolkit
node_notion_toolkit -->|"REST calls"| node_notion_api

click node_cli_entry "https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/__main__.py"
click node_cli_session "https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/session.py"
click node_cli_prompt_tool "https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/tools/generate_jwt.py"
click node_ticket_watcher "https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/ticket_watcher.py"
click node_django_entry "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/manage.py"
click node_api_router "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/urls.py"
click node_api_handlers "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/views/toolkits.py"
click node_auth_tokens "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/authentication.py"
click node_policy_validation "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/permissions.py"
click node_approval_audit "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/audit.py"
click node_toolkit_registry "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/__init__.py"
click node_gateway_models "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/models.py"
click node_seed_catalog "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/management/commands/seed.py"
click node_mock_toolkits "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/items/executors.py"
click node_notion_toolkit "https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/notion/executors.py"

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_django_entry,node_api_router,node_api_handlers,node_auth_tokens,node_policy_validation,node_approval_audit,node_toolkit_registry,node_gateway_models,node_sqlite,node_seed_catalog,node_mock_toolkits,node_notion_toolkit toneBlue
class node_cli_entry,node_cli_session,node_cli_prompt_tool,node_ticket_watcher toneAmber
class node_anthropic,node_notion_api toneMint
```

## Components

### Django Gateway

Enforcement, approval, and audit boundary.

- [Django app](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/manage.py): backend entrypoint · `backend/manage.py`
- [Gateway API routes](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/urls.py): Django routing · Exposes token and external-services endpoints. · `backend/external_services/urls.py`
- [API handlers](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/views/toolkits.py): DRF views · Handles discovery, action calls, approvals, permissions, and audit queries. · `backend/external_services/views/toolkits.py`
- [JWT & Basic auth](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/authentication.py): authentication · JWT identifies agents; Basic auth gates human administration. · `backend/external_services/authentication.py`
- [Policy & schema validation](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/permissions.py): authorization pipeline · Resolves override/default policy and validates persisted action schemas. · `backend/external_services/permissions.py`
- [Approvals & audit](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/audit.py): workflow service · Creates tickets, lazily expires them, and records pending and terminal events. · `backend/external_services/audit.py`
- [Toolkit registry](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/__init__.py): executor dispatch · Dispatches cataloged actions to isolated toolkit executors. · `backend/external_services/toolkits/__init__.py`
- [Gateway domain models](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/models.py): Django ORM · Stores agents, catalog, overrides, tickets, and snapshot-based audit history. · `backend/external_services/models.py`
- **SQLite metadata**: database · Persists gateway metadata only.
- [Catalog seed command](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/management/commands/seed.py): provisioning command · Idempotently provisions the demo agent and action catalog. · `backend/external_services/management/commands/seed.py`
- [Items/GitHub mock toolkits](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/items/executors.py): in-memory executors · Mutate process-local stores. · `backend/external_services/toolkits/items/executors.py`
- [Notion toolkit](https://github.com/kushagrasaxena28/crator-assignment/blob/main/backend/external_services/toolkits/notion/executors.py): live REST executor · Uses environment-provided credentials for live Notion calls. · `backend/external_services/toolkits/notion/executors.py`

### Agent CLI

Interactive Claude Agent SDK process.

- [CLI entrypoint](https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/__main__.py): Python CLI · `agent-cli/agent_cli_script/__main__.py`
- [Claude session](https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/session.py): session orchestration · Hosts the interactive model session and token cache. · `agent-cli/agent_cli_script/session.py`
- [Instructions & JWT tool](https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/tools/generate_jwt.py): model tool · `agent-cli/agent_cli_script/tools/generate_jwt.py`
- [Ticket watcher](https://github.com/kushagrasaxena28/crator-assignment/blob/main/agent-cli/agent_cli_script/ticket_watcher.py): async poller · Polls ticket status and emits approval notifications. · `agent-cli/agent_cli_script/ticket_watcher.py`

### External Systems

- **Anthropic API**: model API
- **Notion REST API**: external service

## Connections

- CLI entrypoint → Claude session: starts
- Claude session → Instructions & JWT tool: provides tool
- Claude session → Ticket watcher: runs watcher
- Claude session → Anthropic API: interactive session
- Claude session → Gateway API routes: Bash/curl API calls
- Ticket watcher → Gateway API routes: polls tickets
- Django app → Gateway API routes: serves
- Gateway API routes → API handlers: routes requests
- API handlers → JWT & Basic auth: authenticates
- API handlers → Policy & schema validation: authorizes action calls
- Policy & schema validation → Gateway domain models: reads policy and schema
- Policy & schema validation → Approvals & audit: creates approval or audit outcome
- Policy & schema validation → Toolkit registry: dispatches allowed actions
- API handlers → Approvals & audit: resolves and queries tickets
- Approvals & audit → Gateway domain models: persists tickets and events
- Gateway domain models → SQLite metadata: ORM persistence
- Catalog seed command → Gateway domain models: provisions catalog
- Toolkit registry → Items/GitHub mock toolkits: dispatches mock actions
- Toolkit registry → Notion toolkit: dispatches live actions
- Notion toolkit → Notion REST API: REST calls