# lucasotw/sextant architecture

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

- Interactive diagram: https://gitdiagram.com/lucasotw/sextant
- Repository: https://github.com/lucasotw/sextant

## Overview

Sextant is a web app for finding and exploring scholarly literature. The main journey runs from search and topic browsing to an article page, where readers can inspect metadata, access an open PDF, get an optional AI summary, and follow related works. Signed-in readers can save articles into lists, annotate them, and revisit highlights and citations; recommendations and MCP access extend that library. The README documents several capabilities whose implementation was not sampled, so those subsystem links are shown at the documented level rather than as inferred internal call chains.

Main entry points: [`src/lib/openalex.ts`](https://github.com/lucasotw/sextant/blob/main/src/lib/openalex.ts) (OpenAlex client), [`src/app/article/[id]/page.tsx`](https://github.com/lucasotw/sextant/blob/main/src/app/article/%5Bid%5D/page.tsx) (Article page), [`src/app/api/favorites/route.ts`](https://github.com/lucasotw/sextant/blob/main/src/app/api/favorites/route.ts) (Library APIs), [`src/app/search/page.tsx`](https://github.com/lucasotw/sextant/blob/main/src/app/search/page.tsx) (Search interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Search &amp; discovery"]
  node_search["Search interface<br/>[page.tsx]"]
  node_searchbox["Search suggestions<br/>[search-box.tsx]"]
  node_suggest["Suggestion API<br/>[route.ts]"]
  node_topics["Topic browsing<br/>[page.tsx]"]
  node_recommendations["Personal recommendations<br/>[route.ts]"]
end

subgraph group_reading["Article reading"]
  node_article["Article page<br/>[page.tsx]"]
  node_author["Author details<br/>[author-chip.tsx]"]
  node_pdf["Open PDF access<br/>[route.ts]"]
  node_summary["AI summary<br/>[route.ts]"]
end

subgraph group_library["Personal library"]
  node_highlights["Highlights &amp; citations"]
  node_notes["Article notes<br/>[article-note.tsx]"]
  node_favorites["Favorites interface"]
  node_collections["Saved lists"]
  node_libraryapi["Library APIs<br/>[route.ts]"]
  node_collectionsapi["Collection API<br/>[route.ts]"]
end

subgraph group_identity["Accounts &amp; access"]
  node_authui["Sign-in interface<br/>[auth-button.tsx]"]
  node_authapi["Session API<br/>[route.ts]"]
  node_auth["Session verification<br/>[auth.ts]"]
end

subgraph group_platform["Server services"]
  node_firebase[("Firestore access<br/>[admin.ts]")]
  node_openalex["OpenAlex client<br/>[openalex.ts]"]
  node_guard["API guards<br/>[guard.ts]"]
  node_mcp["MCP integration<br/>[route.ts]"]
end

node_reader(("Reader"))
node_mistral["Mistral AI"]

node_reader -->|"searches"| node_search
node_reader -->|"browses"| node_topics
node_reader -->|"opens work"| node_article
node_search -.->|"accepts query"| node_searchbox
node_searchbox -->|"requests suggestions"| node_suggest
node_search -.->|"searches works"| node_openalex
node_topics -.->|"loads topic works"| node_openalex
node_article -->|"shows author"| node_author
node_article -->|"requests PDF"| node_pdf
node_pdf -->|"looks up work"| node_openalex
node_article -->|"requests summary"| node_summary
node_summary -->|"loads work"| node_openalex
node_summary -.->|"generates summary"| node_mistral
node_reader -->|"annotates reading"| node_highlights
node_reader -->|"writes notes"| node_notes
node_reader -->|"saves works"| node_favorites
node_favorites -.->|"syncs favorites"| node_libraryapi
node_reader -->|"organizes favorites"| node_collections
node_collections -.->|"manages lists"| node_collectionsapi
node_libraryapi -->|"reads session"| node_auth
node_libraryapi -.->|"stores favorites"| node_firebase
node_collectionsapi -.->|"stores lists"| node_firebase
node_authui -.->|"opens session"| node_authapi
node_authapi -->|"verifies identity"| node_auth
node_auth -->|"checks account"| node_firebase
node_libraryapi -->|"guards writes"| node_guard
node_reader -->|"explores suggestions"| node_recommendations
node_recommendations -->|"ranks works"| node_openalex
node_reader -->|"connects library"| node_mcp
node_mcp -->|"checks requests"| node_guard

click node_search "https://github.com/lucasotw/sextant/blob/main/src/app/search/page.tsx"
click node_searchbox "https://github.com/lucasotw/sextant/blob/main/src/components/search-box.tsx"
click node_suggest "https://github.com/lucasotw/sextant/blob/main/src/app/api/suggest/route.ts"
click node_topics "https://github.com/lucasotw/sextant/blob/main/src/app/theme/%5Bslug%5D/page.tsx"
click node_recommendations "https://github.com/lucasotw/sextant/blob/main/src/app/api/recommendations/route.ts"
click node_article "https://github.com/lucasotw/sextant/blob/main/src/app/article/%5Bid%5D/page.tsx"
click node_author "https://github.com/lucasotw/sextant/blob/main/src/components/author-chip.tsx"
click node_pdf "https://github.com/lucasotw/sextant/blob/main/src/app/api/pdf/route.ts"
click node_summary "https://github.com/lucasotw/sextant/blob/main/src/app/api/summary/route.ts"
click node_highlights "https://github.com/lucasotw/sextant/blob/main/src/components/highlights/article-highlights.tsx"
click node_notes "https://github.com/lucasotw/sextant/blob/main/src/components/notes/article-note.tsx"
click node_favorites "https://github.com/lucasotw/sextant/blob/main/src/components/favorites/favorites-provider.tsx"
click node_collections "https://github.com/lucasotw/sextant/blob/main/src/components/collections/collection-dialog.tsx"
click node_libraryapi "https://github.com/lucasotw/sextant/blob/main/src/app/api/favorites/route.ts"
click node_collectionsapi "https://github.com/lucasotw/sextant/blob/main/src/app/api/collections/route.ts"
click node_firebase "https://github.com/lucasotw/sextant/blob/main/src/lib/firebase/admin.ts"
click node_openalex "https://github.com/lucasotw/sextant/blob/main/src/lib/openalex.ts"
click node_authui "https://github.com/lucasotw/sextant/blob/main/src/components/auth/auth-button.tsx"
click node_authapi "https://github.com/lucasotw/sextant/blob/main/src/app/api/auth/session/route.ts"
click node_auth "https://github.com/lucasotw/sextant/blob/main/src/lib/auth.ts"
click node_guard "https://github.com/lucasotw/sextant/blob/main/src/lib/api/guard.ts"
click node_mcp "https://github.com/lucasotw/sextant/blob/main/src/app/api/mcp/route.ts"

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_search,node_searchbox,node_suggest,node_topics,node_recommendations toneBlue
class node_article,node_author,node_pdf,node_summary toneAmber
class node_highlights,node_notes,node_favorites,node_collections,node_libraryapi,node_collectionsapi toneMint
class node_authui,node_authapi,node_auth toneRose
class node_firebase,node_openalex,node_guard,node_mcp,node_reader,node_mistral toneIndigo
```

## Components

### Search & discovery

- [Search interface](https://github.com/lucasotw/sextant/blob/main/src/app/search/page.tsx): `src/app/search/page.tsx`
- [Search suggestions](https://github.com/lucasotw/sextant/blob/main/src/components/search-box.tsx): `src/components/search-box.tsx`
- [Suggestion API](https://github.com/lucasotw/sextant/blob/main/src/app/api/suggest/route.ts): `src/app/api/suggest/route.ts`
- [Topic browsing](https://github.com/lucasotw/sextant/blob/main/src/app/theme/%5Bslug%5D/page.tsx): `src/app/theme/[slug]/page.tsx`
- [Personal recommendations](https://github.com/lucasotw/sextant/blob/main/src/app/api/recommendations/route.ts): `src/app/api/recommendations/route.ts`

### Article reading

- [Article page](https://github.com/lucasotw/sextant/blob/main/src/app/article/%5Bid%5D/page.tsx): `src/app/article/[id]/page.tsx`
- [Author details](https://github.com/lucasotw/sextant/blob/main/src/components/author-chip.tsx): `src/components/author-chip.tsx`
- [Open PDF access](https://github.com/lucasotw/sextant/blob/main/src/app/api/pdf/route.ts): `src/app/api/pdf/route.ts`
- [AI summary](https://github.com/lucasotw/sextant/blob/main/src/app/api/summary/route.ts): `src/app/api/summary/route.ts`

### Personal library

- [Highlights & citations](https://github.com/lucasotw/sextant/blob/main/src/components/highlights/article-highlights.tsx): `src/components/highlights/article-highlights.tsx`
- [Article notes](https://github.com/lucasotw/sextant/blob/main/src/components/notes/article-note.tsx): `src/components/notes/article-note.tsx`
- [Favorites interface](https://github.com/lucasotw/sextant/blob/main/src/components/favorites/favorites-provider.tsx): `src/components/favorites/favorites-provider.tsx`
- [Saved lists](https://github.com/lucasotw/sextant/blob/main/src/components/collections/collection-dialog.tsx): `src/components/collections/collection-dialog.tsx`
- [Library APIs](https://github.com/lucasotw/sextant/blob/main/src/app/api/favorites/route.ts): `src/app/api/favorites/route.ts`
- [Collection API](https://github.com/lucasotw/sextant/blob/main/src/app/api/collections/route.ts): `src/app/api/collections/route.ts`

### Accounts & access

- [Sign-in interface](https://github.com/lucasotw/sextant/blob/main/src/components/auth/auth-button.tsx): `src/components/auth/auth-button.tsx`
- [Session API](https://github.com/lucasotw/sextant/blob/main/src/app/api/auth/session/route.ts): `src/app/api/auth/session/route.ts`
- [Session verification](https://github.com/lucasotw/sextant/blob/main/src/lib/auth.ts): `src/lib/auth.ts`

### Server services

- [Firestore access](https://github.com/lucasotw/sextant/blob/main/src/lib/firebase/admin.ts): `src/lib/firebase/admin.ts`
- [OpenAlex client](https://github.com/lucasotw/sextant/blob/main/src/lib/openalex.ts): `src/lib/openalex.ts`
- [API guards](https://github.com/lucasotw/sextant/blob/main/src/lib/api/guard.ts): `src/lib/api/guard.ts`
- [MCP integration](https://github.com/lucasotw/sextant/blob/main/src/app/api/mcp/route.ts): `src/app/api/mcp/route.ts`

### Other components

- **Reader**
- **Mistral AI**

## Connections

- Reader → Search interface: searches
- Reader → Topic browsing: browses
- Reader → Article page: opens work
- Search interface → Search suggestions: accepts query
- Search suggestions → Suggestion API: requests suggestions (evidence: `src/components/search-box.tsx`)
- Search interface → OpenAlex client: searches works
- Topic browsing → OpenAlex client: loads topic works
- Article page → Author details: shows author
- Article page → Open PDF access: requests PDF
- Open PDF access → OpenAlex client: looks up work (evidence: `src/app/api/pdf/route.ts`)
- Article page → AI summary: requests summary
- AI summary → OpenAlex client: loads work (evidence: `src/app/api/summary/route.ts`)
- AI summary → Mistral AI: generates summary
- Reader → Highlights & citations: annotates reading
- Reader → Article notes: writes notes
- Reader → Favorites interface: saves works
- Favorites interface → Library APIs: syncs favorites
- Reader → Saved lists: organizes favorites
- Saved lists → Collection API: manages lists
- Library APIs → Session verification: reads session (evidence: `src/app/api/favorites/route.ts`)
- Library APIs → Firestore access: stores favorites
- Collection API → Firestore access: stores lists
- Sign-in interface → Session API: opens session
- Session API → Session verification: verifies identity (evidence: `src/app/api/auth/session/route.ts`)
- Session verification → Firestore access: checks account (evidence: `src/lib/auth.ts`)
- Library APIs → API guards: guards writes (evidence: `src/lib/api/guard.ts`)
- Reader → Personal recommendations: explores suggestions
- Personal recommendations → OpenAlex client: ranks works (evidence: `src/app/api/recommendations/route.ts`)
- Reader → MCP integration: connects library
- MCP integration → API guards: checks requests (evidence: `src/app/api/mcp/route.ts`)
