# youuujiiin/scope-narrative-consistency-analysis-system architecture

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

- Interactive diagram: https://gitdiagram.com/youuujiiin/scope-narrative-consistency-analysis-system
- Repository: https://github.com/youuujiiin/scope-narrative-consistency-analysis-system

## Overview

Glitch is a web application for detecting continuity problems in long-form narratives. Its main workflow is to submit a chapter, extract structured canon data, let the user confirm that data, then review it against the established canon and surface contradictions. The backend separates API, services, pipeline adapters, and persistence; analysis work can run through worker tasks. The AI server provides the analysis side of the pipeline, including extraction, review, entity resolution, and embeddings. The README is empty, and several routes and AI modules were not sampled, so uncertain connections are left out or marked unverified.

Main entry points: [`app/main.py`](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/main.py) (API application), [`ai_server/scope_ai/workflow.py`](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/scope_ai/workflow.py) (Analysis workflow), [`app/repository`](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/repository) (Domain repositories), [`app/pipeline`](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/pipeline) (Pipeline adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web client"]
  node_frontend["Web interface<br/>[script.js]"]
end

subgraph group_backend["Application backend"]
  node_api_app["API application<br/>[main.py]"]
  node_chapter_api["Chapter routes<br/>[chapters.py]"]
  node_pipeline_api["Pipeline health route<br/>[pipeline.py]"]
  node_chapter_service["Chapter workflow<br/>[chapter_service.py]"]
  node_pipeline_service["Pipeline health check"]
  node_job_tasks["Analysis tasks<br/>[tasks.py]"]
  node_worker["Background worker<br/>[worker.py]"]
end

subgraph group_analysis["Narrative analysis"]
  node_pipeline_contract["Analysis contract<br/>[interface.py]"]
  node_pipeline_adapters["Pipeline adapters"]
  node_ai_server["AI service<br/>[main.py]"]
  node_ai_bridge["Scope bridge<br/>[scope_bridge.py]"]
  node_scope_workflow["Analysis workflow<br/>[workflow.py]"]
  node_entity_resolution["Entity resolution"]
  node_embeddings["Event embeddings"]
  node_review["Contradiction review<br/>[reviewer.py]"]
end

subgraph group_persistence["Persistence"]
  node_repositories["Domain repositories"]
  node_database[("Application database<br/>[db.py]")]
end

subgraph group_extensions["Account and collaboration"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_chat["Chat assistant<br/>[assistant.py]"]
  node_sharing["Sharing service<br/>[share_service.py]"]
  node_notifications["Notifications"]
end

node_user(("Writer"))

node_user -.->|"uses"| node_frontend
node_api_app -->|"registers"| node_chapter_api
node_api_app -->|"registers"| node_pipeline_api
node_pipeline_api -->|"checks health"| node_pipeline_service
node_pipeline_service -->|"selects adapter"| node_pipeline_adapters
node_pipeline_adapters -->|"implements"| node_pipeline_contract
node_chapter_service -->|"calls analysis"| node_pipeline_contract
node_chapter_service -->|"reads and writes"| node_repositories
node_job_tasks -->|"calls extraction and review"| node_pipeline_contract
node_job_tasks -->|"records results"| node_repositories
node_worker -->|"runs tasks"| node_job_tasks
node_pipeline_adapters -.->|"calls remotely"| node_ai_server
node_ai_server -->|"dispatches"| node_ai_bridge
node_ai_bridge -.->|"hands off analysis"| node_scope_workflow
node_scope_workflow -.->|"uses identifiers"| node_entity_resolution
node_scope_workflow -.->|"uses embeddings"| node_embeddings
node_scope_workflow -.->|"performs review"| node_review
node_repositories -.->|"persists domain data"| node_database
node_auth -->|"uses account storage"| node_repositories
node_api_app -->|"conditionally registers"| node_chat
node_api_app -->|"conditionally registers"| node_sharing
node_api_app -->|"conditionally registers"| node_notifications

click node_frontend "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/frontend/script.js"
click node_api_app "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/main.py"
click node_chapter_api "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/api/chapters.py"
click node_pipeline_api "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/api/pipeline.py"
click node_chapter_service "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/chapter_service.py"
click node_pipeline_service "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/pipeline_service.py"
click node_pipeline_contract "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/pipeline/interface.py"
click node_pipeline_adapters "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/pipeline"
click node_job_tasks "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/workers/tasks.py"
click node_worker "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/workers/worker.py"
click node_ai_server "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/server/main.py"
click node_ai_bridge "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/server/scope_bridge.py"
click node_scope_workflow "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/scope_ai/workflow.py"
click node_entity_resolution "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/ai_server/scope_ai/id_split"
click node_embeddings "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/ai_server/scope_ai/embedding"
click node_review "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/scope_ai/review/reviewer.py"
click node_repositories "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/repository"
click node_database "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/core/db.py"
click node_auth "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/auth_service.py"
click node_chat "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/chat/assistant.py"
click node_sharing "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/share_service.py"
click node_notifications "https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/notification_service.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_frontend toneBlue
class node_api_app,node_chapter_api,node_pipeline_api,node_chapter_service,node_pipeline_service,node_job_tasks,node_worker toneAmber
class node_pipeline_contract,node_pipeline_adapters,node_ai_server,node_ai_bridge,node_scope_workflow,node_entity_resolution,node_embeddings,node_review toneMint
class node_repositories,node_database toneRose
class node_auth,node_chat,node_sharing,node_notifications,node_user toneIndigo
```

## Components

### Web client

- [Web interface](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/frontend/script.js): `frontend/script.js`

### Application backend

- [API application](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/main.py): `app/main.py`
- [Chapter routes](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/api/chapters.py): `app/api/chapters.py`
- [Pipeline health route](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/api/pipeline.py): `app/api/pipeline.py`
- [Chapter workflow](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/chapter_service.py): `app/service/chapter_service.py`
- [Pipeline health check](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/pipeline_service.py): `app/service/pipeline_service.py`
- [Analysis tasks](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/workers/tasks.py): `app/workers/tasks.py`
- [Background worker](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/workers/worker.py): `app/workers/worker.py`

### Narrative analysis

- [Analysis contract](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/pipeline/interface.py): `app/pipeline/interface.py`
- [Pipeline adapters](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/pipeline): `app/pipeline`
- [AI service](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/server/main.py): `ai_server/server/main.py`
- [Scope bridge](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/server/scope_bridge.py): `ai_server/server/scope_bridge.py`
- [Analysis workflow](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/scope_ai/workflow.py): `ai_server/scope_ai/workflow.py`
- [Entity resolution](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/ai_server/scope_ai/id_split): `ai_server/scope_ai/id_split`
- [Event embeddings](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/ai_server/scope_ai/embedding): `ai_server/scope_ai/embedding`
- [Contradiction review](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/ai_server/scope_ai/review/reviewer.py): `ai_server/scope_ai/review/reviewer.py`

### Persistence

- [Domain repositories](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/tree/main/app/repository): `app/repository`
- [Application database](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/core/db.py): `app/core/db.py`

### Account and collaboration

- [Authentication](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/auth_service.py): `app/service/auth_service.py`
- [Chat assistant](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/chat/assistant.py): `app/chat/assistant.py`
- [Sharing service](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/share_service.py): `app/service/share_service.py`
- [Notifications](https://github.com/youuujiiin/scope-narrative-consistency-analysis-system/blob/main/app/service/notification_service.py): `app/service/notification_service.py`

### Other components

- **Writer**

## Connections

- Writer → Web interface: uses
- API application → Chapter routes: registers (evidence: `app/main.py`)
- API application → Pipeline health route: registers (evidence: `app/main.py`)
- Pipeline health route → Pipeline health check: checks health (evidence: `app/api/pipeline.py`)
- Pipeline health check → Pipeline adapters: selects adapter (evidence: `app/service/pipeline_service.py`)
- Pipeline adapters → Analysis contract: implements (evidence: `app/pipeline/factory.py`)
- Chapter workflow → Analysis contract: calls analysis (evidence: `app/service/chapter_service.py`)
- Chapter workflow → Domain repositories: reads and writes (evidence: `app/service/chapter_service.py`)
- Analysis tasks → Analysis contract: calls extraction and review (evidence: `app/workers/tasks.py`)
- Analysis tasks → Domain repositories: records results (evidence: `app/workers/tasks.py`)
- Background worker → Analysis tasks: runs tasks (evidence: `app/workers/worker.py`)
- Pipeline adapters → AI service: calls remotely
- AI service → Scope bridge: dispatches (evidence: `ai_server/server/main.py`)
- Scope bridge → Analysis workflow: hands off analysis
- Analysis workflow → Entity resolution: uses identifiers
- Analysis workflow → Event embeddings: uses embeddings
- Analysis workflow → Contradiction review: performs review
- Domain repositories → Application database: persists domain data
- Authentication → Domain repositories: uses account storage (evidence: `app/service/auth_service.py`)
- API application → Chat assistant: conditionally registers (evidence: `app/main.py`)
- API application → Sharing service: conditionally registers (evidence: `app/main.py`)
- API application → Notifications: conditionally registers (evidence: `app/main.py`)