# sk-sathyavada-008/eventscout_mobilefirst architecture

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

- Interactive diagram: https://gitdiagram.com/sk-sathyavada-008/eventscout_mobilefirst
- Repository: https://github.com/sk-sathyavada-008/eventscout_mobilefirst

## Overview

EventScout discovers technical events, curates them into personalized recommendations, and delivers them through a web app, browser extension, and notifications. The graph follows the documented collection-to-ranking workflow and includes source discovery and approval, user-facing access, and alert delivery. Some subsystem connections are based on the README rather than sampled implementation; uncertain wiring is omitted.

Main entry points: [`eventscout/services/scraper_service.py`](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/scraper_service.py) (Scraper Service), [`eventscout/services/notification_service.py`](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/notification_service.py) (Notification Service), [`api/main.py`](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/api/main.py) (FastAPI), [`eventscout/services/llm_service.py`](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/llm_service.py) (Source Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Source Discovery"]
  node_source_agent["Source Discovery<br/>[llm_service.py]"]
  node_source_registry[("Source Registry<br/>[source_db.py]")]
end

subgraph group_collection["Collection Pipeline"]
  node_scraper["Scraper Service<br/>[scraper_service.py]"]
  node_collectors["Source Collectors"]
  node_normalize["Event Normalizer<br/>[normalizer.py]"]
  node_dedupe["Event Deduplicator<br/>[deduplicator.py]"]
  node_filter["Technical Filter"]
  node_ranking["Personalized Ranking<br/>[ranking_service.py]"]
  node_scheduler["Pipeline Scheduler<br/>[scheduler.py]"]
end

subgraph group_platform["API and Data"]
  node_api["FastAPI<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_event_db[("Event Store<br/>[mongodb.py]")]
  node_user_db[("User Store<br/>[user_db.py]")]
end

subgraph group_experience["User Experience"]
  node_web["Next.js App"]
  node_extension["Chrome Extension"]
end

subgraph group_alerts["Notifications"]
  node_notification_service["Notification Service"]
  node_email_service["Email Digests<br/>[email_service.py]"]
  node_notification_db[("Notification Store<br/>[notification_db.py]")]
end

node_public_sites(("Event Platforms"))
node_gemini{{"Gemini AI"}}
node_admin(("Source Admin"))
node_user(("Developer"))
node_smtp{{"SMTP Service"}}

node_public_sites -->|"provides pages"| node_source_agent
node_source_agent -.->|"analyzes pages"| node_gemini
node_source_agent -->|"submits recipes"| node_source_registry
node_admin -->|"approves sources"| node_source_registry
node_scheduler -->|"runs pipeline"| node_scraper
node_scraper -->|"reads enabled sources"| node_source_registry
node_scraper -->|"dispatches collection"| node_collectors
node_collectors -->|"fetches events"| node_public_sites
node_scraper -->|"normalizes events"| node_normalize
node_scraper -->|"deduplicates events"| node_dedupe
node_scraper -->|"filters events"| node_filter
node_scraper -->|"ranks events"| node_ranking
node_scraper -->|"stores events"| node_event_db
node_user -->|"uses app"| node_web
node_web -->|"requests data"| node_api
node_extension -->|"saves events"| node_api
node_api -->|"queries and writes"| node_event_db
node_api -->|"routes authentication"| node_auth
node_auth -->|"reads and writes users"| node_user_db
node_api -->|"reads user data"| node_user_db
node_scheduler -->|"triggers alerts"| node_notification_service
node_notification_service -->|"reads events"| node_event_db
node_notification_service -->|"reads preferences"| node_user_db
node_notification_service -->|"checks alert history"| node_notification_db
node_notification_service -->|"sends digests"| node_email_service
node_email_service -.->|"delivers email"| node_smtp

click node_source_agent "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/llm_service.py"
click node_source_registry "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/source_db.py"
click node_scraper "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/scraper_service.py"
click node_collectors "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/eventscout/collectors"
click node_normalize "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/processors/normalizer.py"
click node_dedupe "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/processors/deduplicator.py"
click node_filter "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/filters/technical_filter.py"
click node_ranking "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/ranking_service.py"
click node_scheduler "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/scheduler.py"
click node_api "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/api/main.py"
click node_auth "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/api/routers/auth.py"
click node_event_db "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/mongodb.py"
click node_user_db "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/user_db.py"
click node_web "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/frontend/src/app"
click node_extension "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/extension"
click node_notification_service "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/notification_service.py"
click node_email_service "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/email_service.py"
click node_notification_db "https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/notification_db.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_source_agent,node_source_registry toneBlue
class node_scraper,node_collectors,node_normalize,node_dedupe,node_filter,node_ranking,node_scheduler toneAmber
class node_api,node_auth,node_event_db,node_user_db toneMint
class node_web,node_extension toneRose
class node_notification_service,node_email_service,node_notification_db,node_public_sites,node_gemini,node_admin,node_user,node_smtp toneIndigo
```

## Components

### Source Discovery

- [Source Discovery](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/llm_service.py): `eventscout/services/llm_service.py`
- [Source Registry](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/source_db.py): `eventscout/database/source_db.py`

### Collection Pipeline

- [Scraper Service](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/scraper_service.py): `eventscout/services/scraper_service.py`
- [Source Collectors](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/eventscout/collectors): `eventscout/collectors`
- [Event Normalizer](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/processors/normalizer.py): `eventscout/processors/normalizer.py`
- [Event Deduplicator](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/processors/deduplicator.py): `eventscout/processors/deduplicator.py`
- [Technical Filter](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/filters/technical_filter.py): `eventscout/filters/technical_filter.py`
- [Personalized Ranking](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/ranking_service.py): `eventscout/services/ranking_service.py`
- [Pipeline Scheduler](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/scheduler.py): `eventscout/scheduler.py`

### API and Data

- [FastAPI](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/api/main.py): `api/main.py`
- [Authentication](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/api/routers/auth.py): `api/routers/auth.py`
- [Event Store](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/mongodb.py): `eventscout/database/mongodb.py`
- [User Store](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/user_db.py): `eventscout/database/user_db.py`

### User Experience

- [Next.js App](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/frontend/src/app): `frontend/src/app`
- [Chrome Extension](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/tree/main/extension): `extension`

### Notifications

- [Notification Service](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/notification_service.py): `eventscout/services/notification_service.py`
- [Email Digests](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/services/email_service.py): `eventscout/services/email_service.py`
- [Notification Store](https://github.com/sk-sathyavada-008/eventscout_mobilefirst/blob/main/eventscout/database/notification_db.py): `eventscout/database/notification_db.py`

### Other components

- **Event Platforms**
- **Gemini AI**
- **Source Admin**
- **Developer**
- **SMTP Service**

## Connections

- Event Platforms → Source Discovery: provides pages
- Source Discovery → Gemini AI: analyzes pages
- Source Discovery → Source Registry: submits recipes
- Source Admin → Source Registry: approves sources
- Pipeline Scheduler → Scraper Service: runs pipeline
- Scraper Service → Source Registry: reads enabled sources
- Scraper Service → Source Collectors: dispatches collection
- Source Collectors → Event Platforms: fetches events
- Scraper Service → Event Normalizer: normalizes events
- Scraper Service → Event Deduplicator: deduplicates events
- Scraper Service → Technical Filter: filters events
- Scraper Service → Personalized Ranking: ranks events
- Scraper Service → Event Store: stores events
- Developer → Next.js App: uses app
- Next.js App → FastAPI: requests data
- Chrome Extension → FastAPI: saves events
- FastAPI → Event Store: queries and writes
- FastAPI → Authentication: routes authentication
- Authentication → User Store: reads and writes users
- FastAPI → User Store: reads user data
- Pipeline Scheduler → Notification Service: triggers alerts
- Notification Service → Event Store: reads events
- Notification Service → User Store: reads preferences
- Notification Service → Notification Store: checks alert history
- Notification Service → Email Digests: sends digests
- Email Digests → SMTP Service: delivers email