# aadams35/pilarprep-aws architecture

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

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

## Overview

PilarPrep turns customer context into audience-specific briefs, approved handoffs, meeting analysis, and accountable follow-up. The main path runs from the React workspace through the Jobs API and asynchronous worker; the worker branches into brief generation, project state, meeting processing, and AgentCore workflows. The README documents AWS queueing, storage, and malware-scanning services, but their infrastructure definitions are not in the supplied tree. Relationships below use shown imports/calls where available and documented workflow statements otherwise.

Main entry points: [`backend/ai_worker/handler.py`](https://github.com/aadams35/pilarprep-aws/blob/main/backend/ai_worker/handler.py) (AI worker), [`backend/jobs_api/handler.py`](https://github.com/aadams35/pilarprep-aws/blob/main/backend/jobs_api/handler.py) (Jobs API), [`frontend/src/App.tsx`](https://github.com/aadams35/pilarprep-aws/blob/main/frontend/src/App.tsx) (PilarPrep workspace), [`backend/pipeline/meeting.py`](https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/meeting.py) (Meeting processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Customer workspace"]
  node_app["PilarPrep workspace<br/>[App.tsx]"]
  node_meeting_ui["Meeting workspace"]
end

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

subgraph group_briefs["Briefs and evidence"]
  node_brief_engine["Brief generation<br/>[brief_generator.py]"]
  node_evidence["Evidence retrieval<br/>[evidence.py]"]
  node_safety["Content safety<br/>[content_safety.py]"]
end

subgraph group_meetings["Meeting lifecycle"]
  node_meeting_pipeline["Meeting processing<br/>[meeting.py]"]
  node_meeting_contracts["Meeting contracts"]
  node_audio_services["Scan and transcription"]
end

subgraph group_agentcore["Handoffs and catch-up"]
  node_agent_service["AgentCore workflows<br/>[service.py]"]
  node_agent_tools["Governed tools<br/>[handler.py]"]
  node_runtime_gateway["AgentCore gateway<br/>[gateway.py]"]
  node_handoff["Handoff promotion"]
  node_docx["DOCX packets<br/>[docx.py]"]
end

node_user(("Sales / Solutions Architect"))
node_artifact_store[("DynamoDB / S3")]
node_bedrock["Amazon Bedrock"]
node_knowledge_base[("Knowledge Base")]

node_user -->|"prepares context"| node_app
node_app -->|"submits and polls"| node_jobs_api
node_jobs_api -->|"enqueues jobs"| node_queue
node_queue -->|"dispatches jobs"| node_worker
node_jobs_api -->|"tracks jobs"| node_state
node_worker -->|"updates state"| node_state
node_worker -->|"generates briefs"| node_brief_engine
node_worker -->|"retrieves evidence"| node_evidence
node_worker -->|"screens content"| node_safety
node_brief_engine -.->|"invokes models"| node_bedrock
node_evidence -->|"retrieves sources"| node_knowledge_base
node_jobs_api -->|"issues uploads"| node_artifact_store
node_worker -->|"reads and writes"| node_artifact_store
node_app -.->|"presents workflow"| node_meeting_ui
node_meeting_ui -->|"uploads and reviews"| node_jobs_api
node_jobs_api -->|"starts audio processing"| node_audio_services
node_audio_services -->|"returns service events"| node_queue
node_worker -->|"processes meetings"| node_meeting_pipeline
node_meeting_pipeline -->|"validates analysis"| node_meeting_contracts
node_meeting_pipeline -->|"reads and updates"| node_state
node_worker -->|"dispatches workflows"| node_agent_tools
node_agent_tools -->|"renders packets"| node_docx
node_agent_service -->|"generates responses"| node_bedrock
node_agent_service -.->|"uses gateway"| node_runtime_gateway
node_agent_tools -->|"reads and writes state"| node_artifact_store
node_worker -->|"promotes handoffs"| node_handoff
node_user -->|"reviews follow-up"| node_app

click node_app "https://github.com/aadams35/pilarprep-aws/blob/main/frontend/src/App.tsx"
click node_jobs_api "https://github.com/aadams35/pilarprep-aws/blob/main/backend/jobs_api/handler.py"
click node_worker "https://github.com/aadams35/pilarprep-aws/blob/main/backend/ai_worker/handler.py"
click node_brief_engine "https://github.com/aadams35/pilarprep-aws/blob/main/backend/bedrock/brief_generator.py"
click node_evidence "https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/evidence.py"
click node_state "https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/state.py"
click node_safety "https://github.com/aadams35/pilarprep-aws/blob/main/backend/shared/content_safety.py"
click node_meeting_ui "https://github.com/aadams35/pilarprep-aws/blob/main/frontend/src/components/meeting-intelligence.tsx"
click node_meeting_pipeline "https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/meeting.py"
click node_meeting_contracts "https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/meeting_contracts.py"
click node_agent_service "https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/runtime/service.py"
click node_agent_tools "https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/tools/handler.py"
click node_runtime_gateway "https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/runtime/gateway.py"
click node_handoff "https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/handoff_promotion.py"
click node_docx "https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/tools/docx.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_meeting_ui toneBlue
class node_jobs_api,node_queue,node_worker,node_state,node_artifact_store,node_knowledge_base toneAmber
class node_brief_engine,node_evidence,node_safety toneMint
class node_meeting_pipeline,node_meeting_contracts,node_audio_services toneRose
class node_agent_service,node_agent_tools,node_runtime_gateway,node_handoff,node_docx,node_user,node_bedrock toneIndigo
```

## Components

### Customer workspace

- [PilarPrep workspace](https://github.com/aadams35/pilarprep-aws/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Meeting workspace](https://github.com/aadams35/pilarprep-aws/blob/main/frontend/src/components/meeting-intelligence.tsx): `frontend/src/components/meeting-intelligence.tsx`

### Async job processing

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

### Briefs and evidence

- [Brief generation](https://github.com/aadams35/pilarprep-aws/blob/main/backend/bedrock/brief_generator.py): `backend/bedrock/brief_generator.py`
- [Evidence retrieval](https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/evidence.py): `backend/pipeline/evidence.py`
- [Content safety](https://github.com/aadams35/pilarprep-aws/blob/main/backend/shared/content_safety.py): `backend/shared/content_safety.py`

### Meeting lifecycle

- [Meeting processing](https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/meeting.py): `backend/pipeline/meeting.py`
- [Meeting contracts](https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/meeting_contracts.py): `backend/pipeline/meeting_contracts.py`
- **Scan and transcription**

### Handoffs and catch-up

- [AgentCore workflows](https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/runtime/service.py): `backend/agentcore/runtime/service.py`
- [Governed tools](https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/tools/handler.py): `backend/agentcore/tools/handler.py`
- [AgentCore gateway](https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/runtime/gateway.py): `backend/agentcore/runtime/gateway.py`
- [Handoff promotion](https://github.com/aadams35/pilarprep-aws/blob/main/backend/pipeline/handoff_promotion.py): `backend/pipeline/handoff_promotion.py`
- [DOCX packets](https://github.com/aadams35/pilarprep-aws/blob/main/backend/agentcore/tools/docx.py): `backend/agentcore/tools/docx.py`

### Other components

- **Sales / Solutions Architect**
- **DynamoDB / S3**
- **Amazon Bedrock**
- **Knowledge Base**

## Connections

- Sales / Solutions Architect → PilarPrep workspace: prepares context (evidence: `README.md`)
- PilarPrep workspace → Jobs API: submits and polls (evidence: `frontend/src/App.tsx`)
- Jobs API → SQS job queue: enqueues jobs (evidence: `README.md`)
- SQS job queue → AI worker: dispatches jobs (evidence: `README.md`)
- Jobs API → Job and project state: tracks jobs (evidence: `backend/jobs_api/handler.py`)
- AI worker → Job and project state: updates state (evidence: `backend/ai_worker/handler.py`)
- AI worker → Brief generation: generates briefs (evidence: `backend/ai_worker/handler.py`)
- AI worker → Evidence retrieval: retrieves evidence (evidence: `backend/ai_worker/handler.py`)
- AI worker → Content safety: screens content (evidence: `backend/ai_worker/handler.py`)
- Brief generation → Amazon Bedrock: invokes models (evidence: `README.md`)
- Evidence retrieval → Knowledge Base: retrieves sources (evidence: `README.md`)
- Jobs API → DynamoDB / S3: issues uploads (evidence: `backend/jobs_api/handler.py`)
- AI worker → DynamoDB / S3: reads and writes (evidence: `backend/ai_worker/handler.py`)
- PilarPrep workspace → Meeting workspace: presents workflow
- Meeting workspace → Jobs API: uploads and reviews (evidence: `README.md`)
- Jobs API → Scan and transcription: starts audio processing (evidence: `README.md`)
- Scan and transcription → SQS job queue: returns service events (evidence: `README.md`)
- AI worker → Meeting processing: processes meetings (evidence: `backend/ai_worker/handler.py`)
- Meeting processing → Meeting contracts: validates analysis (evidence: `backend/pipeline/meeting.py`)
- Meeting processing → Job and project state: reads and updates (evidence: `backend/pipeline/meeting.py`)
- AI worker → Governed tools: dispatches workflows (evidence: `backend/ai_worker/handler.py`)
- Governed tools → DOCX packets: renders packets (evidence: `backend/agentcore/tools/handler.py`)
- AgentCore workflows → Amazon Bedrock: generates responses (evidence: `backend/agentcore/runtime/service.py`)
- AgentCore workflows → AgentCore gateway: uses gateway (evidence: `backend/agentcore/runtime/service.py`)
- Governed tools → DynamoDB / S3: reads and writes state (evidence: `backend/agentcore/tools/handler.py`)
- AI worker → Handoff promotion: promotes handoffs (evidence: `backend/ai_worker/handler.py`)
- Sales / Solutions Architect → PilarPrep workspace: reviews follow-up (evidence: `README.md`)
