# sushyanth/pilarprep architecture

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

- Interactive diagram: https://gitdiagram.com/sushyanth/pilarprep
- Repository: https://github.com/sushyanth/pilarprep

## Overview

PilarPrep turns customer context into audience-specific briefs, approved handoffs, meeting comparisons, and accountable follow-up. The principal workflow runs from the React workspace through asynchronous jobs to brief generation, review and approval, then handoff or meeting processing; catch-up adds a read-only, role-aware view of approved context. The graph follows the README’s documented queue-and-worker architecture and sampled entry points. Infrastructure details and some service wiring are documented but not present in the supplied tree, so those links are limited to documented flows.

Main entry points: [`backend/ai_worker/handler.py`](https://github.com/sushyanth/pilarprep/blob/main/backend/ai_worker/handler.py) (AI worker), [`backend/jobs_api/handler.py`](https://github.com/sushyanth/pilarprep/blob/main/backend/jobs_api/handler.py) (Jobs API), [`backend/pipeline/meeting.py`](https://github.com/sushyanth/pilarprep/blob/main/backend/pipeline/meeting.py) (Meeting processing), [`backend/agentcore/runtime/service.py`](https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/runtime/service.py) (Agent workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Customer workspace"]
  node_app["React workspace<br/>[App.tsx]"]
  node_jobs_client["Jobs client<br/>[jobs-client.ts]"]
end

subgraph group_jobs["Async job processing"]
  node_jobs_api["Jobs API<br/>[handler.py]"]
  node_queue["SQS jobs"]
  node_worker["AI worker<br/>[handler.py]"]
  node_job_state[("Job and project state")]
end

subgraph group_briefs["Brief and meeting pipeline"]
  node_brief_generation["Brief generation<br/>[brief_generator.py]"]
  node_meeting_pipeline["Meeting processing<br/>[meeting.py]"]
  node_evidence_pipeline["Evidence handling<br/>[evidence.py]"]
  node_artifact_store[("Private artifacts")]
  node_knowledge_base[("Evidence Knowledge Base")]
end

subgraph group_agent["Handoff and catch-up"]
  node_agent_runtime["Agent runtime<br/>[main.py]"]
  node_agent_service["Agent workflows<br/>[service.py]"]
  node_agent_tools["Governed tools<br/>[handler.py]"]
end

node_user(("Sales / SA user"))
node_bedrock{{"Amazon Bedrock"}}
node_meeting_services{{"Scan and transcription"}}

node_user -->|"enters context"| node_app
node_app -->|"requests jobs"| node_jobs_client
node_jobs_client -->|"calls API"| node_jobs_api
node_jobs_api -->|"enqueues job"| node_queue
node_jobs_api -->|"records job"| node_job_state
node_jobs_api -->|"stores input"| node_artifact_store
node_queue -->|"dispatches job"| node_worker
node_worker -->|"updates status"| node_job_state
node_worker -->|"reads and writes"| node_artifact_store
node_worker -->|"generates or refines"| node_brief_generation
node_brief_generation -->|"requests generation"| node_bedrock
node_worker -->|"requests agent work"| node_agent_runtime
node_agent_runtime -->|"handles request"| node_agent_service
node_agent_service -.->|"dispatches tools"| node_agent_tools
node_agent_tools -->|"reads project state"| node_job_state
node_agent_tools -->|"stores handoffs"| node_artifact_store
node_agent_service -.->|"retrieves evidence"| node_knowledge_base
node_worker -->|"processes meeting"| node_meeting_pipeline
node_meeting_pipeline -->|"scans and transcribes"| node_meeting_services
node_meeting_pipeline -->|"handles evidence"| node_evidence_pipeline
node_meeting_pipeline -->|"returns service events"| node_queue
node_worker -.->|"reads evidence"| node_knowledge_base

click node_app "https://github.com/sushyanth/pilarprep/blob/main/frontend/src/App.tsx"
click node_jobs_client "https://github.com/sushyanth/pilarprep/blob/main/frontend/src/lib/jobs-client.ts"
click node_jobs_api "https://github.com/sushyanth/pilarprep/blob/main/backend/jobs_api/handler.py"
click node_worker "https://github.com/sushyanth/pilarprep/blob/main/backend/ai_worker/handler.py"
click node_brief_generation "https://github.com/sushyanth/pilarprep/blob/main/backend/bedrock/brief_generator.py"
click node_meeting_pipeline "https://github.com/sushyanth/pilarprep/blob/main/backend/pipeline/meeting.py"
click node_evidence_pipeline "https://github.com/sushyanth/pilarprep/blob/main/backend/pipeline/evidence.py"
click node_agent_runtime "https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/runtime/main.py"
click node_agent_service "https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/runtime/service.py"
click node_agent_tools "https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/tools/handler.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_app,node_jobs_client,node_user toneBlue
class node_jobs_api,node_queue,node_worker,node_job_state toneAmber
class node_brief_generation,node_meeting_pipeline,node_evidence_pipeline,node_artifact_store,node_knowledge_base toneMint
class node_agent_runtime,node_agent_service,node_agent_tools toneRose
class node_bedrock,node_meeting_services toneIndigo
```

## Components

### Customer workspace

- [React workspace](https://github.com/sushyanth/pilarprep/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Jobs client](https://github.com/sushyanth/pilarprep/blob/main/frontend/src/lib/jobs-client.ts): `frontend/src/lib/jobs-client.ts`

### Async job processing

- [Jobs API](https://github.com/sushyanth/pilarprep/blob/main/backend/jobs_api/handler.py): `backend/jobs_api/handler.py`
- **SQS jobs**
- [AI worker](https://github.com/sushyanth/pilarprep/blob/main/backend/ai_worker/handler.py): `backend/ai_worker/handler.py`
- **Job and project state**

### Brief and meeting pipeline

- [Brief generation](https://github.com/sushyanth/pilarprep/blob/main/backend/bedrock/brief_generator.py): `backend/bedrock/brief_generator.py`
- [Meeting processing](https://github.com/sushyanth/pilarprep/blob/main/backend/pipeline/meeting.py): `backend/pipeline/meeting.py`
- [Evidence handling](https://github.com/sushyanth/pilarprep/blob/main/backend/pipeline/evidence.py): `backend/pipeline/evidence.py`
- **Private artifacts**
- **Evidence Knowledge Base**

### Handoff and catch-up

- [Agent runtime](https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/runtime/main.py): `backend/agentcore/runtime/main.py`
- [Agent workflows](https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/runtime/service.py): `backend/agentcore/runtime/service.py`
- [Governed tools](https://github.com/sushyanth/pilarprep/blob/main/backend/agentcore/tools/handler.py): `backend/agentcore/tools/handler.py`

### Other components

- **Sales / SA user**
- **Amazon Bedrock**
- **Scan and transcription**

## Connections

- Sales / SA user → React workspace: enters context
- React workspace → Jobs client: requests jobs
- Jobs client → Jobs API: calls API
- Jobs API → SQS jobs: enqueues job
- Jobs API → Job and project state: records job
- Jobs API → Private artifacts: stores input
- SQS jobs → AI worker: dispatches job
- AI worker → Job and project state: updates status
- AI worker → Private artifacts: reads and writes
- AI worker → Brief generation: generates or refines
- Brief generation → Amazon Bedrock: requests generation
- AI worker → Agent runtime: requests agent work
- Agent runtime → Agent workflows: handles request
- Agent workflows → Governed tools: dispatches tools
- Governed tools → Job and project state: reads project state
- Governed tools → Private artifacts: stores handoffs
- Agent workflows → Evidence Knowledge Base: retrieves evidence
- AI worker → Meeting processing: processes meeting
- Meeting processing → Scan and transcription: scans and transcribes
- Meeting processing → Evidence handling: handles evidence
- Meeting processing → SQS jobs: returns service events
- AI worker → Evidence Knowledge Base: reads evidence