# narenjcs/assignment architecture

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

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

## Overview

DocIntel is a cross-cloud document-intelligence application. Users upload a PDF or DOCX in the React UI, then follow job status and results or chat about a selected job. The AWS API and upload trigger create and dispatch jobs; an AgentCore orchestrator selects the DOCX or PDF processing path. AWS and Databricks MCP tools bridge document access and result persistence across clouds. The README documents both sync and async processing and result storage in DynamoDB and Unity Catalog. Several connections below rely on that documentation because the corresponding source was not excerpted.

Main entry points: [`databricks/app/src/docintel_app/server.py`](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/server.py) (Databricks MCP server), [`frontend/src/app/App.tsx`](https://github.com/narenjcs/assignment/blob/main/frontend/src/app/App.tsx) (React workspace), [`aws/agents/docx_agent/main.py`](https://github.com/narenjcs/assignment/blob/main/aws/agents/docx_agent/main.py) (DOCX agent), [`aws/lambdas/src/mcp-tools/handler.ts`](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/mcp-tools/handler.ts) (AWS MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_ui["React workspace<br/>[App.tsx]"]
  node_upload["Upload flow<br/>[useUpload.ts]"]
  node_jobview["Jobs and results<br/>[JobsList.tsx]"]
  node_chat["Job chat<br/>[useChatStream.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_aws["AWS application"]
  node_api["HTTP API<br/>[handler.ts]"]
  node_routes["Upload, jobs, chat<br/>[uploads.ts]"]
  node_s3[("Upload storage<br/>[storage.ts]")]
  node_trigger["Upload trigger<br/>[handler.ts]"]
  node_jobs[("Job state<br/>[jobs.ts]")]
  node_aws_mcp["AWS MCP tools<br/>[handler.ts]"]
  node_gateway["AgentCore Gateway<br/>[mcp_backend.py]"]
  node_common["Shared runtime config<br/>[config.py]"]
end

subgraph group_agents["Agent processing"]
  node_orchestrator["Workflow orchestrator<br/>[main.py]"]
  node_workflow["Routing and workflow<br/>[workflow.py]"]
  node_docx["DOCX agent<br/>[main.py]"]
end

subgraph group_dbx["Databricks processing"]
  node_dbx_server["Databricks MCP server<br/>[server.py]"]
  node_dbx_agent["PDF agent<br/>[agent.py]"]
  node_ingest["PDF ingestion<br/>[ingest.py]"]
  node_extract["PDF extraction<br/>[extract.py]"]
  node_enrich["Result enrichment<br/>[enrich.py]"]
  node_persist["Result persistence<br/>[persist.py]"]
  node_uc[("Unity Catalog<br/>[uc.py]")]
end

node_user(("User"))
node_databricks["Databricks services"]
node_bedrock["Bedrock model"]

node_user -->|"uses"| node_ui
node_ui -->|"shows"| node_upload
node_ui -->|"shows"| node_jobview
node_ui -->|"shows"| node_chat
node_upload -->|"calls"| node_api_client
node_jobview -->|"polls"| node_api_client
node_chat -->|"streams"| node_api_client
node_api_client -.->|"requests"| node_api
node_api -->|"dispatches"| node_routes
node_routes -.->|"creates upload"| node_s3
node_s3 -.->|"notifies"| node_trigger
node_trigger -->|"updates status"| node_jobs
node_trigger -->|"invokes async"| node_orchestrator
node_api -.->|"starts processing"| node_orchestrator
node_orchestrator -->|"runs"| node_workflow
node_workflow -.->|"routes DOCX"| node_docx
node_workflow -.->|"routes PDF"| node_dbx_server
node_docx -->|"calls tools"| node_gateway
node_gateway -.->|"connects tools"| node_aws_mcp
node_aws_mcp -.->|"reads document"| node_s3
node_aws_mcp -.->|"writes results"| node_jobs
node_dbx_server -->|"runs agent"| node_dbx_agent
node_dbx_server -->|"registers tool"| node_ingest
node_dbx_server -->|"registers tool"| node_extract
node_dbx_server -->|"registers tool"| node_enrich
node_dbx_server -->|"registers tool"| node_persist
node_ingest -->|"fetches document"| node_aws_mcp
node_ingest -->|"uploads PDF"| node_uc
node_extract -.->|"uses PDF services"| node_databricks
node_enrich -.->|"uses model service"| node_databricks
node_persist -.->|"writes result"| node_uc
node_dbx_agent -.->|"uses model"| node_bedrock
node_docx -->|"uses model"| node_bedrock
node_dbx_server -->|"serves MCP"| node_databricks
node_orchestrator -.->|"tracks job"| node_jobs
node_docx -.->|"saves result"| node_jobs
node_common -.->|"configures client"| node_gateway

click node_ui "https://github.com/narenjcs/assignment/blob/main/frontend/src/app/App.tsx"
click node_upload "https://github.com/narenjcs/assignment/blob/main/frontend/src/features/upload/useUpload.ts"
click node_jobview "https://github.com/narenjcs/assignment/blob/main/frontend/src/features/jobs/JobsList.tsx"
click node_chat "https://github.com/narenjcs/assignment/blob/main/frontend/src/features/chat/useChatStream.ts"
click node_api_client "https://github.com/narenjcs/assignment/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/api/handler.ts"
click node_routes "https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/api/routes/uploads.ts"
click node_s3 "https://github.com/narenjcs/assignment/blob/main/aws/infra/lib/constructs/storage.ts"
click node_trigger "https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/s3-trigger/handler.ts"
click node_jobs "https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/lib/jobs.ts"
click node_orchestrator "https://github.com/narenjcs/assignment/blob/main/aws/agents/orchestrator/main.py"
click node_workflow "https://github.com/narenjcs/assignment/blob/main/aws/agents/orchestrator/workflow.py"
click node_docx "https://github.com/narenjcs/assignment/blob/main/aws/agents/docx_agent/main.py"
click node_aws_mcp "https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/mcp-tools/handler.ts"
click node_gateway "https://github.com/narenjcs/assignment/blob/main/aws/common/docintel_common/mcp_backend.py"
click node_dbx_server "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/server.py"
click node_dbx_agent "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/agent.py"
click node_ingest "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/ingest.py"
click node_extract "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/extract.py"
click node_enrich "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/enrich.py"
click node_persist "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/persist.py"
click node_uc "https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/uc.py"
click node_common "https://github.com/narenjcs/assignment/blob/main/aws/common/docintel_common/config.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_ui,node_upload,node_jobview,node_chat,node_api_client,node_user toneBlue
class node_api,node_routes,node_s3,node_trigger,node_jobs,node_aws_mcp,node_gateway,node_common toneAmber
class node_orchestrator,node_workflow,node_docx toneMint
class node_dbx_server,node_dbx_agent,node_ingest,node_extract,node_enrich,node_persist,node_uc toneRose
class node_databricks,node_bedrock toneIndigo
```

## Components

### Browser experience

- [React workspace](https://github.com/narenjcs/assignment/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Upload flow](https://github.com/narenjcs/assignment/blob/main/frontend/src/features/upload/useUpload.ts): `frontend/src/features/upload/useUpload.ts`
- [Jobs and results](https://github.com/narenjcs/assignment/blob/main/frontend/src/features/jobs/JobsList.tsx): `frontend/src/features/jobs/JobsList.tsx`
- [Job chat](https://github.com/narenjcs/assignment/blob/main/frontend/src/features/chat/useChatStream.ts): `frontend/src/features/chat/useChatStream.ts`
- [API client](https://github.com/narenjcs/assignment/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### AWS application

- [HTTP API](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/api/handler.ts): `aws/lambdas/src/api/handler.ts`
- [Upload, jobs, chat](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/api/routes/uploads.ts): `aws/lambdas/src/api/routes/uploads.ts`
- [Upload storage](https://github.com/narenjcs/assignment/blob/main/aws/infra/lib/constructs/storage.ts): `aws/infra/lib/constructs/storage.ts`
- [Upload trigger](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/s3-trigger/handler.ts): `aws/lambdas/src/s3-trigger/handler.ts`
- [Job state](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/lib/jobs.ts): `aws/lambdas/src/lib/jobs.ts`
- [AWS MCP tools](https://github.com/narenjcs/assignment/blob/main/aws/lambdas/src/mcp-tools/handler.ts): `aws/lambdas/src/mcp-tools/handler.ts`
- [AgentCore Gateway](https://github.com/narenjcs/assignment/blob/main/aws/common/docintel_common/mcp_backend.py): `aws/common/docintel_common/mcp_backend.py`
- [Shared runtime config](https://github.com/narenjcs/assignment/blob/main/aws/common/docintel_common/config.py): `aws/common/docintel_common/config.py`

### Agent processing

- [Workflow orchestrator](https://github.com/narenjcs/assignment/blob/main/aws/agents/orchestrator/main.py): `aws/agents/orchestrator/main.py`
- [Routing and workflow](https://github.com/narenjcs/assignment/blob/main/aws/agents/orchestrator/workflow.py): `aws/agents/orchestrator/workflow.py`
- [DOCX agent](https://github.com/narenjcs/assignment/blob/main/aws/agents/docx_agent/main.py): `aws/agents/docx_agent/main.py`

### Databricks processing

- [Databricks MCP server](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/server.py): `databricks/app/src/docintel_app/server.py`
- [PDF agent](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/agent.py): `databricks/app/src/docintel_app/agent.py`
- [PDF ingestion](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/ingest.py): `databricks/app/src/docintel_app/tools/ingest.py`
- [PDF extraction](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/extract.py): `databricks/app/src/docintel_app/tools/extract.py`
- [Result enrichment](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/enrich.py): `databricks/app/src/docintel_app/tools/enrich.py`
- [Result persistence](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/tools/persist.py): `databricks/app/src/docintel_app/tools/persist.py`
- [Unity Catalog](https://github.com/narenjcs/assignment/blob/main/databricks/app/src/docintel_app/uc.py): `databricks/app/src/docintel_app/uc.py`

### Other components

- **User**
- **Databricks services**
- **Bedrock model**

## Connections

- User → React workspace: uses (evidence: `README.md`)
- React workspace → Upload flow: shows (evidence: `frontend/src/app/App.tsx`)
- React workspace → Jobs and results: shows (evidence: `frontend/src/app/App.tsx`)
- React workspace → Job chat: shows (evidence: `frontend/src/app/App.tsx`)
- Upload flow → API client: calls (evidence: `frontend/src/features/upload/useUpload.ts`)
- Jobs and results → API client: polls
- Job chat → API client: streams (evidence: `frontend/src/features/chat/useChatStream.ts`)
- API client → HTTP API: requests (evidence: `README.md`)
- HTTP API → Upload, jobs, chat: dispatches (evidence: `aws/lambdas/src/api/handler.ts`)
- Upload, jobs, chat → Upload storage: creates upload (evidence: `README.md`)
- Upload storage → Upload trigger: notifies (evidence: `README.md`)
- Upload trigger → Job state: updates status (evidence: `aws/lambdas/src/s3-trigger/handler.ts`)
- Upload trigger → Workflow orchestrator: invokes async (evidence: `aws/lambdas/src/s3-trigger/handler.ts`)
- HTTP API → Workflow orchestrator: starts processing (evidence: `README.md`)
- Workflow orchestrator → Routing and workflow: runs (evidence: `aws/agents/orchestrator/main.py`)
- Routing and workflow → DOCX agent: routes DOCX (evidence: `README.md`)
- Routing and workflow → Databricks MCP server: routes PDF (evidence: `README.md`)
- DOCX agent → AgentCore Gateway: calls tools (evidence: `aws/agents/docx_agent/main.py`)
- AgentCore Gateway → AWS MCP tools: connects tools (evidence: `README.md`)
- AWS MCP tools → Upload storage: reads document (evidence: `README.md`)
- AWS MCP tools → Job state: writes results (evidence: `README.md`)
- Databricks MCP server → PDF agent: runs agent (evidence: `databricks/app/src/docintel_app/server.py`)
- Databricks MCP server → PDF ingestion: registers tool (evidence: `databricks/app/src/docintel_app/server.py`)
- Databricks MCP server → PDF extraction: registers tool (evidence: `databricks/app/src/docintel_app/server.py`)
- Databricks MCP server → Result enrichment: registers tool (evidence: `databricks/app/src/docintel_app/server.py`)
- Databricks MCP server → Result persistence: registers tool (evidence: `databricks/app/src/docintel_app/server.py`)
- PDF ingestion → AWS MCP tools: fetches document (evidence: `databricks/app/src/docintel_app/tools/ingest.py`)
- PDF ingestion → Unity Catalog: uploads PDF (evidence: `databricks/app/src/docintel_app/tools/ingest.py`)
- PDF extraction → Databricks services: uses PDF services (evidence: `README.md`)
- Result enrichment → Databricks services: uses model service (evidence: `README.md`)
- Result persistence → Unity Catalog: writes result (evidence: `README.md`)
- PDF agent → Bedrock model: uses model (evidence: `README.md`)
- DOCX agent → Bedrock model: uses model (evidence: `aws/agents/docx_agent/main.py`)
- Databricks MCP server → Databricks services: serves MCP (evidence: `databricks/app/src/docintel_app/server.py`)
- Workflow orchestrator → Job state: tracks job (evidence: `README.md`)
- DOCX agent → Job state: saves result (evidence: `README.md`)
- Shared runtime config → AgentCore Gateway: configures client (evidence: `aws/agents/docx_agent/main.py`)
