# aaravhmodi/intern-agent architecture

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

- Interactive diagram: https://gitdiagram.com/aaravhmodi/intern-agent
- Repository: https://github.com/aaravhmodi/intern-agent
- Video tour (about a minute): https://gitdiagram.com/aaravhmodi/intern-agent/video

## Overview

This is a local-first internship and opportunity search agent with a dashboard. The main flow discovers and enriches leads, scores them against the resume and preferences, drafts outreach, and supports applications; inbox replies feed a job pipeline. A separate opportunity agent finds, assesses, and can apply or RSVP to events. The graph preserves the documented dashboard, chat, calendar, and notification capabilities. Some edges rely on README documentation or SOURCE INDEX references; unsampled implementation details are not asserted.

Main entry points: [`src/internship_agent/dashboard/app.py`](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/dashboard/app.py) (Dashboard), [`src/internship_agent/workflows.py`](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/workflows.py) (Lead workflows), [`src/internship_agent/opportunities/run.py`](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/run.py) (Event workflow), [`src/internship_agent/leads/store.py`](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/leads/store.py) (Lead records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_chat["Ask chat<br/>[chat.py]"]
  node_agenda["Calendar<br/>[agenda.py]"]
end

subgraph group_internships["Internship search"]
  node_sources["Lead sources"]
  node_regions["Region filters<br/>[regions.py]"]
  node_workflow["Lead workflows<br/>[workflows.py]"]
  node_scoring["Fit and drafts<br/>[ai.py]"]
  node_leadstore[("Lead records<br/>[store.py]")]
  node_answers[("Answer bank<br/>[answers.py]")]
  node_application["Job applications<br/>[browser.py]"]
end

subgraph group_outreach["Outreach and tracking"]
  node_mailer["Email sending<br/>[mailer.py]"]
  node_mailbox["Inbox reader<br/>[mailbox.py]"]
  node_pipeline["Job pipeline<br/>[pipeline.py]"]
end

subgraph group_events["Opportunity search"]
  node_oprun["Event workflow<br/>[run.py]"]
  node_feeds["Event feeds<br/>[feeds.py]"]
  node_eventai["Event assessment<br/>[ai.py]"]
  node_eventapply["Event applications<br/>[apply.py]"]
  node_eventstore[("Event records<br/>[store.py]")]
end

subgraph group_shared["Shared services"]
  node_notify["Notifications<br/>[notify.py]"]
  node_db[("Persistence layer<br/>[db.py]")]
  node_resume["Resume data<br/>[resume.py]"]
end

node_user(("Applicant"))
node_openai{{"OpenAI"}}
node_web{{"Public web"}}
node_gmail{{"Gmail"}}

node_user -->|"uses"| node_dashboard
node_dashboard -->|"runs"| node_workflow
node_workflow -->|"discovers"| node_sources
node_sources -.->|"searches"| node_web
node_workflow -->|"filters by"| node_regions
node_workflow -->|"scores and drafts"| node_scoring
node_scoring -.->|"requests"| node_openai
node_workflow -->|"updates"| node_leadstore
node_leadstore -->|"persists via"| node_db
node_dashboard -->|"reads"| node_leadstore
node_dashboard -->|"prepares applications"| node_application
node_application -->|"uses"| node_answers
node_dashboard -->|"runs"| node_oprun
node_oprun -->|"collects"| node_feeds
node_feeds -.->|"fetches events"| node_web
node_oprun -->|"assesses"| node_eventai
node_eventai -.->|"requests"| node_openai
node_oprun -->|"plans submissions"| node_eventapply
node_oprun -->|"stores events"| node_eventstore
node_eventstore -->|"persists via"| node_db
node_dashboard -->|"sends confirmed email"| node_mailer
node_mailer -.->|"sends"| node_gmail
node_gmail -.->|"provides replies"| node_mailbox
node_dashboard -->|"shows pipeline"| node_pipeline
node_pipeline -->|"reads inbox"| node_mailbox
node_pipeline -->|"matches leads"| node_leadstore
node_dashboard -->|"offers Ask"| node_chat
node_dashboard -->|"shows deadlines"| node_agenda
node_dashboard -.->|"triggers notifications"| node_notify
node_workflow -.->|"uses profile"| node_resume
node_chat -->|"queries"| node_leadstore
node_chat -->|"queries"| node_eventstore

click node_dashboard "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/dashboard/app.py"
click node_chat "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/chat.py"
click node_agenda "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/agenda.py"
click node_sources "https://github.com/aaravhmodi/intern-agent/tree/main/src/internship_agent/sources"
click node_regions "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/sources/regions.py"
click node_workflow "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/workflows.py"
click node_scoring "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/ai.py"
click node_leadstore "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/leads/store.py"
click node_answers "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/leads/answers.py"
click node_application "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/applications/browser.py"
click node_oprun "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/run.py"
click node_feeds "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/feeds.py"
click node_eventai "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/ai.py"
click node_eventapply "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/apply.py"
click node_eventstore "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/store.py"
click node_mailer "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/mailer.py"
click node_mailbox "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/mailbox.py"
click node_pipeline "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/pipeline.py"
click node_notify "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/notify.py"
click node_db "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/db.py"
click node_resume "https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/resume.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_dashboard,node_chat,node_agenda toneBlue
class node_sources,node_regions,node_workflow,node_scoring,node_leadstore,node_answers,node_application toneAmber
class node_mailer,node_mailbox,node_pipeline toneMint
class node_oprun,node_feeds,node_eventai,node_eventapply,node_eventstore toneRose
class node_notify,node_db,node_resume,node_user,node_openai,node_web,node_gmail toneIndigo
```

## Components

### User interface

- [Dashboard](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/dashboard/app.py): `src/internship_agent/dashboard/app.py`
- [Ask chat](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/chat.py): `src/internship_agent/chat.py`
- [Calendar](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/agenda.py): `src/internship_agent/agenda.py`

### Internship search

- [Lead sources](https://github.com/aaravhmodi/intern-agent/tree/main/src/internship_agent/sources): `src/internship_agent/sources`
- [Region filters](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/sources/regions.py): `src/internship_agent/sources/regions.py`
- [Lead workflows](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/workflows.py): `src/internship_agent/workflows.py`
- [Fit and drafts](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/ai.py): `src/internship_agent/ai.py`
- [Lead records](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/leads/store.py): `src/internship_agent/leads/store.py`
- [Answer bank](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/leads/answers.py): `src/internship_agent/leads/answers.py`
- [Job applications](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/applications/browser.py): `src/internship_agent/applications/browser.py`

### Outreach and tracking

- [Email sending](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/mailer.py): `src/internship_agent/mailer.py`
- [Inbox reader](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/mailbox.py): `src/internship_agent/mailbox.py`
- [Job pipeline](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/pipeline.py): `src/internship_agent/pipeline.py`

### Opportunity search

- [Event workflow](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/run.py): `src/internship_agent/opportunities/run.py`
- [Event feeds](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/feeds.py): `src/internship_agent/opportunities/feeds.py`
- [Event assessment](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/ai.py): `src/internship_agent/opportunities/ai.py`
- [Event applications](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/apply.py): `src/internship_agent/opportunities/apply.py`
- [Event records](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/opportunities/store.py): `src/internship_agent/opportunities/store.py`

### Shared services

- [Notifications](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/notify.py): `src/internship_agent/notify.py`
- [Persistence layer](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/db.py): `src/internship_agent/db.py`
- [Resume data](https://github.com/aaravhmodi/intern-agent/blob/main/src/internship_agent/resume.py): `src/internship_agent/resume.py`

### Other components

- **Applicant**
- **OpenAI**
- **Public web**
- **Gmail**

## Connections

- Applicant → Dashboard: uses
- Dashboard → Lead workflows: runs (evidence: `src/internship_agent/dashboard/app.py`)
- Lead workflows → Lead sources: discovers (evidence: `src/internship_agent/workflows.py`)
- Lead sources → Public web: searches (evidence: `src/internship_agent/sources/funding_news.py`)
- Lead workflows → Region filters: filters by (evidence: `src/internship_agent/workflows.py`)
- Lead workflows → Fit and drafts: scores and drafts (evidence: `src/internship_agent/workflows.py`)
- Fit and drafts → OpenAI: requests
- Lead workflows → Lead records: updates (evidence: `src/internship_agent/workflows.py`)
- Lead records → Persistence layer: persists via (evidence: `src/internship_agent/leads/store.py`)
- Dashboard → Lead records: reads (evidence: `src/internship_agent/dashboard/app.py`)
- Dashboard → Job applications: prepares applications (evidence: `src/internship_agent/dashboard/app.py`)
- Job applications → Answer bank: uses (evidence: `src/internship_agent/applications/browser.py`)
- Dashboard → Event workflow: runs (evidence: `src/internship_agent/dashboard/app.py`)
- Event workflow → Event feeds: collects (evidence: `src/internship_agent/opportunities/run.py`)
- Event feeds → Public web: fetches events
- Event workflow → Event assessment: assesses (evidence: `src/internship_agent/opportunities/run.py`)
- Event assessment → OpenAI: requests
- Event workflow → Event applications: plans submissions (evidence: `src/internship_agent/opportunities/run.py`)
- Event workflow → Event records: stores events (evidence: `src/internship_agent/opportunities/run.py`)
- Event records → Persistence layer: persists via (evidence: `src/internship_agent/opportunities/store.py`)
- Dashboard → Email sending: sends confirmed email (evidence: `src/internship_agent/dashboard/app.py`)
- Email sending → Gmail: sends
- Gmail → Inbox reader: provides replies
- Dashboard → Job pipeline: shows pipeline (evidence: `src/internship_agent/dashboard/app.py`)
- Job pipeline → Inbox reader: reads inbox (evidence: `src/internship_agent/pipeline.py`)
- Job pipeline → Lead records: matches leads (evidence: `src/internship_agent/pipeline.py`)
- Dashboard → Ask chat: offers Ask (evidence: `src/internship_agent/dashboard/app.py`)
- Dashboard → Calendar: shows deadlines (evidence: `src/internship_agent/dashboard/app.py`)
- Dashboard → Notifications: triggers notifications (evidence: `src/internship_agent/dashboard/app.py`)
- Lead workflows → Resume data: uses profile (evidence: `src/internship_agent/workflows.py`)
- Ask chat → Lead records: queries (evidence: `src/internship_agent/chat.py`)
- Ask chat → Event records: queries (evidence: `src/internship_agent/chat.py`)
