# xeonica/seoul-place-docent architecture

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

- Interactive diagram: https://gitdiagram.com/xeonica/seoul-place-docent
- Repository: https://github.com/xeonica/seoul-place-docent

## Overview

This is a Seoul place-history docent and research archive, with a public MCP interface alongside the web app. The main visitor flow resolves an address, verifies the selected candidate, and returns place context such as regional history, buildings, and coordinates; AI summaries are a separate optional result. The archive supports source research, photo/video collections, and review workflows for captured material and regional or passage evidence. The graph follows documented routes and imports; many unsampled endpoints and integrations are omitted where their connections cannot be verified.

Main entry points: [`app/mcp/route.ts`](https://github.com/xeonica/seoul-place-docent/blob/main/app/mcp/route.ts) (MCP request handler), [`lib/providers.ts`](https://github.com/xeonica/seoul-place-docent/blob/main/lib/providers.ts) (Address and building data), [`app/api/archive/task/route.ts`](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/archive/task/route.ts) (Archive review tasks), [`app/api/place/route.ts`](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/place/route.ts) (Place lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_visitor["Place exploration"]
  node_place_api["Place lookup<br/>[route.ts]"]
  node_summary_api["AI summary route<br/>[route.ts]"]
end

subgraph group_archive["History archive"]
  node_archive_site["Archive explorer<br/>[page.tsx]"]
  node_document_research["Document research"]
  node_document_api["Document research API<br/>[route.ts]"]
  node_photo_research["Photo research<br/>[photo-research.tsx]"]
  node_photo_preview["Photo preview<br/>[PhotoPreview.tsx]"]
  node_video_research["Video research<br/>[video-research.tsx]"]
  node_archive_task["Archive review tasks<br/>[route.ts]"]
end

subgraph group_mcp["MCP interface"]
  node_mcp_route["MCP request handler<br/>[route.ts]"]
end

subgraph group_core["Domain services"]
  node_address_provider["Address and building data<br/>[providers.ts]"]
  node_history["Regional history<br/>[history.ts]"]
  node_ai_summary["AI summaries<br/>[ai-summary.ts]"]
  node_photo_data["Photo research data<br/>[photo-research.ts]"]
  node_archive_db[("Archive database<br/>[archive-db.ts]")]
  node_archive_capture["Capture imports<br/>[archive-capture.ts]"]
  node_region_review["Region review"]
  node_passage_review["Passage review"]
  node_archive_validation["Archive validation"]
  node_mcp_protocol["MCP protocol<br/>[mcp-protocol.ts]"]
  node_mcp_photo["Attached photo reading<br/>[mcp-photo.ts]"]
  node_mcp_map["Photo location mapping<br/>[mcp-map-address.ts]"]
  node_place_answer["Answer validation<br/>[place-answer.ts]"]
  node_audit["MCP audit<br/>[mcp-audit.ts]"]
end

node_visitor(("Visitor"))
node_provider_services(("Address and building providers"))
node_ai_provider(("AI provider"))

node_visitor -->|"requests place"| node_place_api
node_place_api -->|"verifies and queries"| node_address_provider
node_place_api -->|"matches regions"| node_history
node_address_provider -.->|"fetches records"| node_provider_services
node_visitor -->|"requests summary"| node_summary_api
node_summary_api -->|"verifies address"| node_address_provider
node_summary_api -->|"generates summary"| node_ai_summary
node_ai_summary -->|"uses history"| node_history
node_ai_summary -.->|"generates text"| node_ai_provider
node_visitor -->|"browses research"| node_archive_site
node_archive_site -->|"opens research"| node_document_research
node_document_research -->|"loads research"| node_document_api
node_visitor -->|"browses photos"| node_photo_research
node_photo_research -->|"filters records"| node_photo_data
node_photo_research -->|"renders preview"| node_photo_preview
node_archive_site -->|"opens video research"| node_video_research
node_archive_task -->|"reads archive"| node_archive_db
node_archive_task -->|"imports captures"| node_archive_capture
node_archive_task -->|"verifies regions"| node_region_review
node_archive_task -->|"reviews passages"| node_passage_review
node_region_review -->|"searches addresses"| node_address_provider
node_passage_review -->|"checks evidence"| node_archive_validation
node_visitor -->|"calls MCP tools"| node_mcp_route
node_mcp_route -->|"formats results"| node_mcp_protocol
node_mcp_route -->|"reads attachment"| node_mcp_photo
node_mcp_route -->|"maps photo location"| node_mcp_map
node_mcp_route -->|"validates answers"| node_place_answer
node_mcp_route -->|"searches and verifies"| node_address_provider
node_mcp_route -->|"records audit"| node_audit

click node_place_api "https://github.com/xeonica/seoul-place-docent/blob/main/app/api/place/route.ts"
click node_address_provider "https://github.com/xeonica/seoul-place-docent/blob/main/lib/providers.ts"
click node_history "https://github.com/xeonica/seoul-place-docent/blob/main/lib/history.ts"
click node_summary_api "https://github.com/xeonica/seoul-place-docent/blob/main/app/api/ai-summary/route.ts"
click node_ai_summary "https://github.com/xeonica/seoul-place-docent/blob/main/lib/ai-summary.ts"
click node_archive_site "https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/page.tsx"
click node_document_research "https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/document-research/document-research.tsx"
click node_document_api "https://github.com/xeonica/seoul-place-docent/blob/main/app/api/archive/document-research/route.ts"
click node_photo_research "https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/photo-research/photo-research.tsx"
click node_photo_data "https://github.com/xeonica/seoul-place-docent/blob/main/lib/photo-research.ts"
click node_photo_preview "https://github.com/xeonica/seoul-place-docent/blob/main/app/components/PhotoPreview.tsx"
click node_video_research "https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/video-research/video-research.tsx"
click node_archive_task "https://github.com/xeonica/seoul-place-docent/blob/main/app/api/archive/task/route.ts"
click node_archive_db "https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-db.ts"
click node_archive_capture "https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-capture.ts"
click node_region_review "https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-region-review.ts"
click node_passage_review "https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-passage-review.ts"
click node_archive_validation "https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-validation.ts"
click node_mcp_route "https://github.com/xeonica/seoul-place-docent/blob/main/app/mcp/route.ts"
click node_mcp_protocol "https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-protocol.ts"
click node_mcp_photo "https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-photo.ts"
click node_mcp_map "https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-map-address.ts"
click node_place_answer "https://github.com/xeonica/seoul-place-docent/blob/main/lib/place-answer.ts"
click node_audit "https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-audit.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_place_api,node_summary_api toneBlue
class node_archive_site,node_document_research,node_document_api,node_photo_research,node_photo_preview,node_video_research,node_archive_task toneAmber
class node_mcp_route toneMint
class node_address_provider,node_history,node_ai_summary,node_photo_data,node_archive_db,node_archive_capture,node_region_review,node_passage_review,node_archive_validation,node_mcp_protocol,node_mcp_photo,node_mcp_map,node_place_answer,node_audit toneRose
class node_visitor,node_provider_services,node_ai_provider toneIndigo
```

## Components

### Place exploration

- [Place lookup](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/place/route.ts): `app/api/place/route.ts`
- [AI summary route](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/ai-summary/route.ts): `app/api/ai-summary/route.ts`

### History archive

- [Archive explorer](https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/page.tsx): `app/archive/page.tsx`
- [Document research](https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/document-research/document-research.tsx): `app/archive/document-research/document-research.tsx`
- [Document research API](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/archive/document-research/route.ts): `app/api/archive/document-research/route.ts`
- [Photo research](https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/photo-research/photo-research.tsx): `app/archive/photo-research/photo-research.tsx`
- [Photo preview](https://github.com/xeonica/seoul-place-docent/blob/main/app/components/PhotoPreview.tsx): `app/components/PhotoPreview.tsx`
- [Video research](https://github.com/xeonica/seoul-place-docent/blob/main/app/archive/video-research/video-research.tsx): `app/archive/video-research/video-research.tsx`
- [Archive review tasks](https://github.com/xeonica/seoul-place-docent/blob/main/app/api/archive/task/route.ts): `app/api/archive/task/route.ts`

### MCP interface

- [MCP request handler](https://github.com/xeonica/seoul-place-docent/blob/main/app/mcp/route.ts): `app/mcp/route.ts`

### Domain services

- [Address and building data](https://github.com/xeonica/seoul-place-docent/blob/main/lib/providers.ts): `lib/providers.ts`
- [Regional history](https://github.com/xeonica/seoul-place-docent/blob/main/lib/history.ts): `lib/history.ts`
- [AI summaries](https://github.com/xeonica/seoul-place-docent/blob/main/lib/ai-summary.ts): `lib/ai-summary.ts`
- [Photo research data](https://github.com/xeonica/seoul-place-docent/blob/main/lib/photo-research.ts): `lib/photo-research.ts`
- [Archive database](https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-db.ts): `lib/archive-db.ts`
- [Capture imports](https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-capture.ts): `lib/archive-capture.ts`
- [Region review](https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-region-review.ts): `lib/archive-region-review.ts`
- [Passage review](https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-passage-review.ts): `lib/archive-passage-review.ts`
- [Archive validation](https://github.com/xeonica/seoul-place-docent/blob/main/lib/archive-validation.ts): `lib/archive-validation.ts`
- [MCP protocol](https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-protocol.ts): `lib/mcp-protocol.ts`
- [Attached photo reading](https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-photo.ts): `lib/mcp-photo.ts`
- [Photo location mapping](https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-map-address.ts): `lib/mcp-map-address.ts`
- [Answer validation](https://github.com/xeonica/seoul-place-docent/blob/main/lib/place-answer.ts): `lib/place-answer.ts`
- [MCP audit](https://github.com/xeonica/seoul-place-docent/blob/main/lib/mcp-audit.ts): `lib/mcp-audit.ts`

### Other components

- **Visitor**
- **Address and building providers**
- **AI provider**

## Connections

- Visitor → Place lookup: requests place (evidence: `app/api/place/route.ts`)
- Place lookup → Address and building data: verifies and queries (evidence: `app/api/place/route.ts`)
- Place lookup → Regional history: matches regions (evidence: `app/api/place/route.ts`)
- Address and building data → Address and building providers: fetches records (evidence: `lib/providers.ts`)
- Visitor → AI summary route: requests summary (evidence: `app/api/ai-summary/route.ts`)
- AI summary route → Address and building data: verifies address (evidence: `app/api/ai-summary/route.ts`)
- AI summary route → AI summaries: generates summary (evidence: `app/api/ai-summary/route.ts`)
- AI summaries → Regional history: uses history (evidence: `lib/ai-summary.ts`)
- AI summaries → AI provider: generates text
- Visitor → Archive explorer: browses research (evidence: `app/archive/page.tsx`)
- Archive explorer → Document research: opens research (evidence: `app/archive/page.tsx`)
- Document research → Document research API: loads research (evidence: `app/archive/document-research/document-research.tsx`)
- Visitor → Photo research: browses photos (evidence: `app/archive/photo-research/photo-research.tsx`)
- Photo research → Photo research data: filters records (evidence: `app/archive/photo-research/photo-research.tsx`)
- Photo research → Photo preview: renders preview (evidence: `app/archive/photo-research/photo-research.tsx`)
- Archive explorer → Video research: opens video research (evidence: `app/archive/page.tsx`)
- Archive review tasks → Archive database: reads archive (evidence: `app/api/archive/task/route.ts`)
- Archive review tasks → Capture imports: imports captures (evidence: `app/api/archive/task/route.ts`)
- Archive review tasks → Region review: verifies regions (evidence: `app/api/archive/task/route.ts`)
- Archive review tasks → Passage review: reviews passages (evidence: `app/api/archive/task/route.ts`)
- Region review → Address and building data: searches addresses (evidence: `lib/archive-region-review.ts`)
- Passage review → Archive validation: checks evidence (evidence: `lib/archive-passage-review.ts`)
- Visitor → MCP request handler: calls MCP tools (evidence: `app/mcp/route.ts`)
- MCP request handler → MCP protocol: formats results (evidence: `app/mcp/route.ts`)
- MCP request handler → Attached photo reading: reads attachment (evidence: `app/mcp/route.ts`)
- MCP request handler → Photo location mapping: maps photo location (evidence: `app/mcp/route.ts`)
- MCP request handler → Answer validation: validates answers (evidence: `app/mcp/route.ts`)
- MCP request handler → Address and building data: searches and verifies (evidence: `app/mcp/route.ts`)
- MCP request handler → MCP audit: records audit (evidence: `app/mcp/route.ts`)