# jutver/etymos architecture

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

- Interactive diagram: https://gitdiagram.com/jutver/etymos
- Repository: https://github.com/jutver/etymos

## Overview

Etymos is a plagiarism-checking application with a customer web app, a separate admin portal, and a Python API/backend. The main user workflow is to submit text or a document, track an asynchronous check, and review a report with matched sources and document previews. The sampled pipeline shows extraction, metadata-based paper search, matching, verification, and report building. The README is a generic Vite template; unsampled frontend and backend capabilities are represented only where the tree or excerpts support them, so uncertain implementation links are omitted.

Main entry points: [`backend/main.py`](https://github.com/jutver/etymos/blob/main/backend/main.py) (Check orchestration), [`backend/api/app.py`](https://github.com/jutver/etymos/blob/main/backend/api/app.py) (Check API), [`apps/web/src/App.tsx`](https://github.com/jutver/etymos/blob/main/apps/web/src/App.tsx) (Web app routes), [`apps/web/src/lib/api.ts`](https://github.com/jutver/etymos/blob/main/apps/web/src/lib/api.ts) (Web API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer app"]
  node_web["Web app routes<br/>[App.tsx]"]
  node_upload["Upload and checks<br/>[index.tsx]"]
  node_reportui["Report review<br/>[index.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_backend["Check backend"]
  node_api["Check API<br/>[app.py]"]
  node_jobs["Job tracking<br/>[job_manager.py]"]
  node_pipeline["Check orchestration<br/>[main.py]"]
  node_extract["Document extraction<br/>[extractor.py]"]
  node_metadata["Metadata and queries<br/>[llm_metadata.py]"]
  node_search["Paper search<br/>[search_sources.py]"]
  node_match["Similarity and verification"]
  node_reports["Report building"]
  node_rewrite["AI rewrite<br/>[ai_rewrite.py]"]
  node_preview["PDF preview<br/>[marker_preview.py]"]
  node_reportstore["Report persistence<br/>[report_store.py]"]
end

subgraph group_admin["Admin portal"]
  node_adminui["Admin workflows<br/>[App.tsx]"]
  node_adminqueries["Admin queries<br/>[api.ts]"]
end

subgraph group_state["Persistence"]
  node_supabase[("Supabase<br/>[supabase_client.py]")]
  node_paper_cache[("Paper cache<br/>[paper_cache.py]")]
end

node_user(("Student or user"))
node_academic{{"Academic search services"}}

node_user -->|"uses"| node_web
node_web -->|"routes"| node_upload
node_upload -->|"submits checks"| node_webapi
node_webapi -->|"calls"| node_api
node_api -->|"creates and reads"| node_jobs
node_api -->|"dispatches checks"| node_pipeline
node_pipeline -->|"extracts text"| node_extract
node_pipeline -->|"builds queries"| node_metadata
node_pipeline -->|"searches papers"| node_search
node_pipeline -->|"verifies matches"| node_match
node_pipeline -->|"builds report"| node_reports
node_pipeline -->|"caches papers"| node_paper_cache
node_search -->|"queries"| node_academic
node_api -->|"reads and writes"| node_reportstore
node_reportstore -->|"persists reports"| node_supabase
node_api -.->|"starts preview"| node_preview
node_reportui -->|"loads report"| node_webapi
node_web -->|"routes"| node_reportui
node_user -->|"administers"| node_adminui
node_adminui -->|"requests data"| node_adminqueries
node_adminqueries -->|"calls"| node_api
node_api -->|"rewrites text"| node_rewrite

click node_web "https://github.com/jutver/etymos/blob/main/apps/web/src/App.tsx"
click node_upload "https://github.com/jutver/etymos/blob/main/apps/web/src/screens/Upload/index.tsx"
click node_reportui "https://github.com/jutver/etymos/blob/main/apps/web/src/screens/Report/index.tsx"
click node_webapi "https://github.com/jutver/etymos/blob/main/apps/web/src/lib/api.ts"
click node_adminui "https://github.com/jutver/etymos/blob/main/apps/admin/src/App.tsx"
click node_adminqueries "https://github.com/jutver/etymos/blob/main/apps/admin/src/lib/api.ts"
click node_api "https://github.com/jutver/etymos/blob/main/backend/api/app.py"
click node_jobs "https://github.com/jutver/etymos/blob/main/backend/api/job_manager.py"
click node_pipeline "https://github.com/jutver/etymos/blob/main/backend/main.py"
click node_extract "https://github.com/jutver/etymos/blob/main/backend/extractor.py"
click node_metadata "https://github.com/jutver/etymos/blob/main/backend/llm_metadata.py"
click node_search "https://github.com/jutver/etymos/blob/main/backend/search_paper/search_sources.py"
click node_match "https://github.com/jutver/etymos/blob/main/backend/sentence_matcher.py"
click node_reports "https://github.com/jutver/etymos/blob/main/backend/final_report_builder.py"
click node_rewrite "https://github.com/jutver/etymos/blob/main/backend/ai_rewrite.py"
click node_preview "https://github.com/jutver/etymos/blob/main/backend/marker_preview.py"
click node_reportstore "https://github.com/jutver/etymos/blob/main/backend/api/report_store.py"
click node_supabase "https://github.com/jutver/etymos/blob/main/backend/api/supabase_client.py"
click node_paper_cache "https://github.com/jutver/etymos/blob/main/backend/paper_cache.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_web,node_upload,node_reportui,node_webapi,node_user toneBlue
class node_api,node_jobs,node_pipeline,node_extract,node_metadata,node_search,node_match,node_reports,node_rewrite,node_preview,node_reportstore toneAmber
class node_adminui,node_adminqueries toneMint
class node_supabase,node_paper_cache toneRose
class node_academic toneIndigo
```

## Components

### Customer app

- [Web app routes](https://github.com/jutver/etymos/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Upload and checks](https://github.com/jutver/etymos/blob/main/apps/web/src/screens/Upload/index.tsx): `apps/web/src/screens/Upload/index.tsx`
- [Report review](https://github.com/jutver/etymos/blob/main/apps/web/src/screens/Report/index.tsx): `apps/web/src/screens/Report/index.tsx`
- [Web API client](https://github.com/jutver/etymos/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### Check backend

- [Check API](https://github.com/jutver/etymos/blob/main/backend/api/app.py): `backend/api/app.py`
- [Job tracking](https://github.com/jutver/etymos/blob/main/backend/api/job_manager.py): `backend/api/job_manager.py`
- [Check orchestration](https://github.com/jutver/etymos/blob/main/backend/main.py): `backend/main.py`
- [Document extraction](https://github.com/jutver/etymos/blob/main/backend/extractor.py): `backend/extractor.py`
- [Metadata and queries](https://github.com/jutver/etymos/blob/main/backend/llm_metadata.py): `backend/llm_metadata.py`
- [Paper search](https://github.com/jutver/etymos/blob/main/backend/search_paper/search_sources.py): `backend/search_paper/search_sources.py`
- [Similarity and verification](https://github.com/jutver/etymos/blob/main/backend/sentence_matcher.py): `backend/sentence_matcher.py`
- [Report building](https://github.com/jutver/etymos/blob/main/backend/final_report_builder.py): `backend/final_report_builder.py`
- [AI rewrite](https://github.com/jutver/etymos/blob/main/backend/ai_rewrite.py): `backend/ai_rewrite.py`
- [PDF preview](https://github.com/jutver/etymos/blob/main/backend/marker_preview.py): `backend/marker_preview.py`
- [Report persistence](https://github.com/jutver/etymos/blob/main/backend/api/report_store.py): `backend/api/report_store.py`

### Admin portal

- [Admin workflows](https://github.com/jutver/etymos/blob/main/apps/admin/src/App.tsx): `apps/admin/src/App.tsx`
- [Admin queries](https://github.com/jutver/etymos/blob/main/apps/admin/src/lib/api.ts): `apps/admin/src/lib/api.ts`

### Persistence

- [Supabase](https://github.com/jutver/etymos/blob/main/backend/api/supabase_client.py): `backend/api/supabase_client.py`
- [Paper cache](https://github.com/jutver/etymos/blob/main/backend/paper_cache.py): `backend/paper_cache.py`

### Other components

- **Student or user**
- **Academic search services**

## Connections

- Student or user → Web app routes: uses
- Web app routes → Upload and checks: routes
- Upload and checks → Web API client: submits checks
- Web API client → Check API: calls
- Check API → Job tracking: creates and reads
- Check API → Check orchestration: dispatches checks
- Check orchestration → Document extraction: extracts text
- Check orchestration → Metadata and queries: builds queries
- Check orchestration → Paper search: searches papers
- Check orchestration → Similarity and verification: verifies matches
- Check orchestration → Report building: builds report
- Check orchestration → Paper cache: caches papers
- Paper search → Academic search services: queries
- Check API → Report persistence: reads and writes
- Report persistence → Supabase: persists reports
- Check API → PDF preview: starts preview
- Report review → Web API client: loads report
- Web app routes → Report review: routes
- Student or user → Admin workflows: administers
- Admin workflows → Admin queries: requests data
- Admin queries → Check API: calls
- Check API → AI rewrite: rewrites text