# mathusigans/newschorin_back architecture

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

- Interactive diagram: https://gitdiagram.com/mathusigans/newschorin_back
- Repository: https://github.com/mathusigans/newschorin_back

## Overview

NewsChorin is a Tamil-news backend: source spiders collect articles, a sync workflow classifies and optionally paraphrases them before storing them, and APIs serve public news and admin moderation. The graph preserves classification, image handling, operations, and authentication as distinct capabilities. Some links are grounded in README statements or SOURCE INDEX references rather than complete excerpts; those references show named dependencies, not necessarily the exact runtime call sequence.

Main entry points: [`app/main.py`](https://github.com/mathusigans/newschorin_back/blob/main/app/main.py) (FastAPI application), [`app/services/admin_service.py`](https://github.com/mathusigans/newschorin_back/blob/main/app/services/admin_service.py) (Moderation workflow), [`app/services/sync_service.py`](https://github.com/mathusigans/newschorin_back/blob/main/app/services/sync_service.py) (Article sync workflow), [`app/api/routes/operations.py`](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/operations.py) (Operations routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_application["FastAPI application<br/>[main.py]"]
  node_public_routes["Public news routes<br/>[news.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_operations_routes["Operations routes<br/>[operations.py]"]
  node_classification_routes["Classification routes<br/>[classification.py]"]
  node_system_routes["System routes<br/>[system.py]"]
end

subgraph group_services["News workflows"]
  node_news_service["Public news workflow<br/>[news_service.py]"]
  node_admin_service["Moderation workflow<br/>[admin_service.py]"]
  node_sync_service["Article sync workflow<br/>[sync_service.py]"]
  node_scraper_service["Scraper service<br/>[scraper_service.py]"]
  node_image_service["Image service<br/>[image_service.py]"]
end

subgraph group_collection["Collection pipeline"]
  node_spiders["News spiders<br/>[base_news.py]"]
  node_news_json["Scraped article data"]
end

subgraph group_persistence["Persistence and media"]
  node_repository["News repository<br/>[news_repository.py]"]
  node_database[("PostgreSQL")]
  node_image_files["Image files"]
  node_connection["DB connection<br/>[connection.py]"]
  node_schema["Schema management<br/>[schema.py]"]
end

subgraph group_support["Classification and integrations"]
  node_classifier_service["Classification service"]
  node_classifier["Tamil classifier<br/>[classifier.py]"]
  node_keywords["Category keywords"]
  node_gemini["Gemini paraphrasing<br/>[gemini_client.py]"]
  node_security["Access control<br/>[security.py]"]
end

node_reader(("News reader"))
node_operator(("Admin / operator"))
node_spider_runner["Scraper runner<br/>[run_all.py]"]

node_application -->|"registers"| node_public_routes
node_application -->|"registers"| node_admin_routes
node_application -->|"registers"| node_auth_routes
node_application -->|"registers"| node_operations_routes
node_application -->|"registers"| node_classification_routes
node_application -->|"registers"| node_system_routes
node_reader -->|"requests news"| node_public_routes
node_operator -->|"moderates articles"| node_admin_routes
node_operator -->|"authenticates"| node_auth_routes
node_operator -->|"runs operations"| node_operations_routes
node_public_routes -->|"delegates to"| node_news_service
node_admin_routes -->|"delegates to"| node_admin_service
node_operations_routes -->|"delegates to"| node_sync_service
node_operations_routes -->|"delegates to"| node_admin_service
node_classification_routes -->|"delegates to"| node_classifier_service
node_admin_routes -->|"checks access"| node_security
node_auth_routes -->|"uses access control"| node_security
node_operations_routes -->|"checks access"| node_security
node_news_service -->|"queries articles"| node_repository
node_admin_service -->|"reads and updates"| node_repository
node_sync_service -->|"upserts articles"| node_repository
node_repository -.->|"reads and writes"| node_database
node_news_service -->|"opens connection"| node_connection
node_admin_service -->|"opens connection"| node_connection
node_sync_service -->|"opens connection"| node_connection
node_application -->|"initializes schema"| node_schema
node_schema -->|"creates tables"| node_database
node_admin_service -->|"reclassifies articles"| node_classifier_service
node_sync_service -->|"classifies articles"| node_classifier_service
node_classifier_service -->|"delegates classification"| node_classifier
node_classifier -->|"uses keyword fallback"| node_keywords
node_sync_service -->|"requests paraphrasing"| node_gemini
node_admin_service -->|"requests paraphrasing"| node_gemini
node_spider_runner -->|"runs configured spiders"| node_spiders
node_spiders -->|"writes scraped data"| node_news_json
node_spider_runner -.->|"syncs results"| node_sync_service
node_news_json -->|"reads article data"| node_sync_service
node_spider_runner -.->|"can invoke workflow"| node_scraper_service
node_scraper_service -->|"uses image service"| node_image_service
node_image_service -->|"normalizes image paths"| node_repository
node_image_service -->|"inspects image directory"| node_image_files
node_admin_service -->|"saves uploaded images"| node_image_files
node_reader -.->|"loads article images"| node_image_files

click node_spider_runner "https://github.com/mathusigans/newschorin_back/blob/main/run_all.py"
click node_application "https://github.com/mathusigans/newschorin_back/blob/main/app/main.py"
click node_public_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/news.py"
click node_admin_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/admin.py"
click node_auth_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/auth.py"
click node_operations_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/operations.py"
click node_classification_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/classification.py"
click node_system_routes "https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/system.py"
click node_news_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/news_service.py"
click node_admin_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/admin_service.py"
click node_sync_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/sync_service.py"
click node_scraper_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/scraper_service.py"
click node_image_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/image_service.py"
click node_spiders "https://github.com/mathusigans/newschorin_back/blob/main/spiders/base_news.py"
click node_repository "https://github.com/mathusigans/newschorin_back/blob/main/app/repositories/news_repository.py"
click node_classifier_service "https://github.com/mathusigans/newschorin_back/blob/main/app/services/classification_service.py"
click node_classifier "https://github.com/mathusigans/newschorin_back/blob/main/classifier.py"
click node_keywords "https://github.com/mathusigans/newschorin_back/blob/main/category_keywords.py"
click node_gemini "https://github.com/mathusigans/newschorin_back/blob/main/app/integrations/gemini_client.py"
click node_security "https://github.com/mathusigans/newschorin_back/blob/main/app/core/security.py"
click node_connection "https://github.com/mathusigans/newschorin_back/blob/main/app/db/connection.py"
click node_schema "https://github.com/mathusigans/newschorin_back/blob/main/app/db/schema.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_application,node_public_routes,node_admin_routes,node_auth_routes,node_operations_routes,node_classification_routes,node_system_routes toneBlue
class node_news_service,node_admin_service,node_sync_service,node_scraper_service,node_image_service toneAmber
class node_spiders,node_news_json toneMint
class node_repository,node_database,node_image_files,node_connection,node_schema toneRose
class node_classifier_service,node_classifier,node_keywords,node_gemini,node_security,node_reader,node_operator toneIndigo
class node_spider_runner toneTeal
```

## Components

### HTTP API

- [FastAPI application](https://github.com/mathusigans/newschorin_back/blob/main/app/main.py): `app/main.py`
- [Public news routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/news.py): `app/api/routes/news.py`
- [Admin routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/admin.py): `app/api/routes/admin.py`
- [Authentication routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Operations routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/operations.py): `app/api/routes/operations.py`
- [Classification routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/classification.py): `app/api/routes/classification.py`
- [System routes](https://github.com/mathusigans/newschorin_back/blob/main/app/api/routes/system.py): `app/api/routes/system.py`

### News workflows

- [Public news workflow](https://github.com/mathusigans/newschorin_back/blob/main/app/services/news_service.py): `app/services/news_service.py`
- [Moderation workflow](https://github.com/mathusigans/newschorin_back/blob/main/app/services/admin_service.py): `app/services/admin_service.py`
- [Article sync workflow](https://github.com/mathusigans/newschorin_back/blob/main/app/services/sync_service.py): `app/services/sync_service.py`
- [Scraper service](https://github.com/mathusigans/newschorin_back/blob/main/app/services/scraper_service.py): `app/services/scraper_service.py`
- [Image service](https://github.com/mathusigans/newschorin_back/blob/main/app/services/image_service.py): `app/services/image_service.py`

### Collection pipeline

- [News spiders](https://github.com/mathusigans/newschorin_back/blob/main/spiders/base_news.py): `spiders/base_news.py`
- **Scraped article data**

### Persistence and media

- [News repository](https://github.com/mathusigans/newschorin_back/blob/main/app/repositories/news_repository.py): `app/repositories/news_repository.py`
- **PostgreSQL**
- **Image files**
- [DB connection](https://github.com/mathusigans/newschorin_back/blob/main/app/db/connection.py): `app/db/connection.py`
- [Schema management](https://github.com/mathusigans/newschorin_back/blob/main/app/db/schema.py): `app/db/schema.py`

### Classification and integrations

- [Classification service](https://github.com/mathusigans/newschorin_back/blob/main/app/services/classification_service.py): `app/services/classification_service.py`
- [Tamil classifier](https://github.com/mathusigans/newschorin_back/blob/main/classifier.py): `classifier.py`
- [Category keywords](https://github.com/mathusigans/newschorin_back/blob/main/category_keywords.py): `category_keywords.py`
- [Gemini paraphrasing](https://github.com/mathusigans/newschorin_back/blob/main/app/integrations/gemini_client.py): `app/integrations/gemini_client.py`
- [Access control](https://github.com/mathusigans/newschorin_back/blob/main/app/core/security.py): `app/core/security.py`

### Other components

- **News reader**
- **Admin / operator**
- [Scraper runner](https://github.com/mathusigans/newschorin_back/blob/main/run_all.py): `run_all.py`

## Connections

- FastAPI application → Public news routes: registers (evidence: `app/main.py`)
- FastAPI application → Admin routes: registers (evidence: `app/main.py`)
- FastAPI application → Authentication routes: registers (evidence: `app/main.py`)
- FastAPI application → Operations routes: registers (evidence: `app/main.py`)
- FastAPI application → Classification routes: registers (evidence: `app/main.py`)
- FastAPI application → System routes: registers (evidence: `app/main.py`)
- News reader → Public news routes: requests news (evidence: `README.md`)
- Admin / operator → Admin routes: moderates articles (evidence: `README.md`)
- Admin / operator → Authentication routes: authenticates (evidence: `README.md`)
- Admin / operator → Operations routes: runs operations (evidence: `README.md`)
- Public news routes → Public news workflow: delegates to (evidence: `app/api/routes/news.py`)
- Admin routes → Moderation workflow: delegates to (evidence: `app/api/routes/admin.py`)
- Operations routes → Article sync workflow: delegates to (evidence: `app/api/routes/operations.py`)
- Operations routes → Moderation workflow: delegates to (evidence: `app/api/routes/operations.py`)
- Classification routes → Classification service: delegates to (evidence: `app/api/routes/classification.py`)
- Admin routes → Access control: checks access (evidence: `app/api/routes/admin.py`)
- Authentication routes → Access control: uses access control (evidence: `app/api/routes/auth.py`)
- Operations routes → Access control: checks access (evidence: `app/api/routes/operations.py`)
- Public news workflow → News repository: queries articles (evidence: `app/services/news_service.py`)
- Moderation workflow → News repository: reads and updates (evidence: `app/services/admin_service.py`)
- Article sync workflow → News repository: upserts articles (evidence: `app/services/sync_service.py`)
- News repository → PostgreSQL: reads and writes
- Public news workflow → DB connection: opens connection (evidence: `app/services/news_service.py`)
- Moderation workflow → DB connection: opens connection (evidence: `app/services/admin_service.py`)
- Article sync workflow → DB connection: opens connection (evidence: `app/services/sync_service.py`)
- FastAPI application → Schema management: initializes schema (evidence: `app/main.py`)
- Schema management → PostgreSQL: creates tables (evidence: `app/db/schema.py`)
- Moderation workflow → Classification service: reclassifies articles (evidence: `app/services/admin_service.py`)
- Article sync workflow → Classification service: classifies articles (evidence: `app/services/sync_service.py`)
- Classification service → Tamil classifier: delegates classification (evidence: `app/services/classification_service.py`)
- Tamil classifier → Category keywords: uses keyword fallback (evidence: `classifier.py`)
- Article sync workflow → Gemini paraphrasing: requests paraphrasing (evidence: `app/services/sync_service.py`)
- Moderation workflow → Gemini paraphrasing: requests paraphrasing (evidence: `app/services/admin_service.py`)
- Scraper runner → News spiders: runs configured spiders (evidence: `README.md`)
- News spiders → Scraped article data: writes scraped data (evidence: `README.md`)
- Scraper runner → Article sync workflow: syncs results
- Scraped article data → Article sync workflow: reads article data (evidence: `app/services/sync_service.py`)
- Scraper runner → Scraper service: can invoke workflow
- Scraper service → Image service: uses image service (evidence: `app/services/scraper_service.py`)
- Image service → News repository: normalizes image paths (evidence: `app/services/image_service.py`)
- Image service → Image files: inspects image directory (evidence: `app/services/image_service.py`)
- Moderation workflow → Image files: saves uploaded images (evidence: `app/services/admin_service.py`)
- News reader → Image files: loads article images
