# robungid/stashify architecture

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

- Interactive diagram: https://gitdiagram.com/robungid/stashify
- Repository: https://github.com/robungid/stashify

## Overview

Stashify is an async Telegram knowledge-resource manager. Users register and browse, search, view, rate, and favorite learning resources; administrators and managers maintain resources, categories, quizzes, and users. The shown search path runs from a Telegram update through the registered bot router, resource service, repository abstraction, and SQL-backed persistence. The README documents additional capabilities, but unsampled routers and providers limit verification of their internal call paths; those branches are represented without asserting unshown calls.

Main entry points: [`app/main.py`](https://github.com/robungid/stashify/blob/main/app/main.py) (Bot runtime), [`app/application/services/resource_item.py`](https://github.com/robungid/stashify/blob/main/app/application/services/resource_item.py) (Resource service), [`app/infrastructure/repositories/sql/resource_item.py`](https://github.com/robungid/stashify/blob/main/app/infrastructure/repositories/sql/resource_item.py) (Resource SQL repository), [`app/application/routers/search_resource.py`](https://github.com/robungid/stashify/blob/main/app/application/routers/search_resource.py) (Resource search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram interaction"]
  node_bot_runtime["Bot runtime<br/>[main.py]"]
  node_resource_search["Resource search<br/>[search_resource.py]"]
  node_resource_browse["Resource browsing<br/>[resources.py]"]
  node_resource_admin["Resource management"]
  node_category_admin["Category management"]
  node_quiz_admin["Quiz management<br/>[manage_quizes.py]"]
  node_user_admin["User management<br/>[manage_users.py]"]
  node_menu["Main menu<br/>[menu.py]"]
end

subgraph group_domain["Resource and quiz domain"]
  node_resource_domain["Resource entities<br/>[resource_item.py]"]
  node_category_domain["Category entities<br/>[category_item.py]"]
  node_quiz_domain["Quiz entities<br/>[quiz_question.py]"]
  node_repository_contract["Repository contracts<br/>[resource_item.py]"]
end

subgraph group_application["Application services"]
  node_resource_service["Resource service<br/>[resource_item.py]"]
  node_service_registry["Service providers<br/>[services.py]"]
end

subgraph group_persistence["SQL persistence"]
  node_sql_resource_repo["Resource SQL repository<br/>[resource_item.py]"]
  node_resource_mapper["Resource mapper<br/>[resource_item.py]"]
  node_resource_model[("Resource table model<br/>[resource_item.py]")]
  node_category_sql_repo["Category SQL repository<br/>[category_item.py]"]
  node_database["Database setup<br/>[init.py]"]
end

node_telegram_user(("Telegram user"))
node_postgres[("PostgreSQL")]

node_telegram_user -->|"sends updates"| node_bot_runtime
node_bot_runtime -->|"registers router"| node_resource_search
node_bot_runtime -->|"registers router"| node_resource_browse
node_bot_runtime -->|"registers router"| node_resource_admin
node_bot_runtime -->|"registers router"| node_category_admin
node_bot_runtime -->|"registers router"| node_quiz_admin
node_bot_runtime -->|"registers router"| node_user_admin
node_bot_runtime -->|"registers router"| node_menu
node_resource_search -->|"queries resources"| node_resource_service
node_resource_service -->|"uses contract"| node_repository_contract
node_service_registry -->|"provides service"| node_resource_service
node_sql_resource_repo -->|"implements contract"| node_repository_contract
node_sql_resource_repo -->|"maps records"| node_resource_mapper
node_resource_mapper -->|"converts model"| node_resource_model
node_category_sql_repo -->|"maps categories"| node_category_domain
node_bot_runtime -->|"initializes models"| node_database
node_database -->|"uses database"| node_postgres
node_resource_browse -.->|"queries resources"| node_resource_service
node_resource_admin -.->|"manages resources"| node_resource_service
node_category_admin -.->|"persists categories"| node_category_sql_repo
node_quiz_admin -.->|"manages quizzes"| node_quiz_domain
node_user_admin -.->|"administers users"| node_bot_runtime
node_resource_model -.->|"stored in"| node_postgres

click node_bot_runtime "https://github.com/robungid/stashify/blob/main/app/main.py"
click node_resource_search "https://github.com/robungid/stashify/blob/main/app/application/routers/search_resource.py"
click node_resource_browse "https://github.com/robungid/stashify/blob/main/app/application/routers/resources.py"
click node_resource_admin "https://github.com/robungid/stashify/blob/main/app/application/routers/manage_resources.py"
click node_category_admin "https://github.com/robungid/stashify/blob/main/app/application/routers/manage_categories.py"
click node_quiz_admin "https://github.com/robungid/stashify/blob/main/app/application/routers/manage_quizes.py"
click node_user_admin "https://github.com/robungid/stashify/blob/main/app/application/routers/manage_users.py"
click node_menu "https://github.com/robungid/stashify/blob/main/app/application/routers/menu.py"
click node_resource_service "https://github.com/robungid/stashify/blob/main/app/application/services/resource_item.py"
click node_service_registry "https://github.com/robungid/stashify/blob/main/app/application/containers/providers/services.py"
click node_resource_domain "https://github.com/robungid/stashify/blob/main/app/domain/entities/resource_item.py"
click node_category_domain "https://github.com/robungid/stashify/blob/main/app/domain/entities/category_item.py"
click node_quiz_domain "https://github.com/robungid/stashify/blob/main/app/domain/entities/quiz_question.py"
click node_repository_contract "https://github.com/robungid/stashify/blob/main/app/domain/repositories/resource_item.py"
click node_sql_resource_repo "https://github.com/robungid/stashify/blob/main/app/infrastructure/repositories/sql/resource_item.py"
click node_resource_mapper "https://github.com/robungid/stashify/blob/main/app/infrastructure/mappers/resource_item.py"
click node_resource_model "https://github.com/robungid/stashify/blob/main/app/infrastructure/models/resource_item.py"
click node_category_sql_repo "https://github.com/robungid/stashify/blob/main/app/infrastructure/repositories/sql/category_item.py"
click node_database "https://github.com/robungid/stashify/blob/main/app/database/init.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_bot_runtime,node_resource_search,node_resource_browse,node_resource_admin,node_category_admin,node_quiz_admin,node_user_admin,node_menu,node_telegram_user toneBlue
class node_resource_domain,node_category_domain,node_quiz_domain,node_repository_contract,node_postgres toneAmber
class node_resource_service,node_service_registry toneMint
class node_sql_resource_repo,node_resource_mapper,node_resource_model,node_category_sql_repo,node_database toneRose
```

## Components

### Telegram interaction

- [Bot runtime](https://github.com/robungid/stashify/blob/main/app/main.py): `app/main.py`
- [Resource search](https://github.com/robungid/stashify/blob/main/app/application/routers/search_resource.py): `app/application/routers/search_resource.py`
- [Resource browsing](https://github.com/robungid/stashify/blob/main/app/application/routers/resources.py): `app/application/routers/resources.py`
- [Resource management](https://github.com/robungid/stashify/blob/main/app/application/routers/manage_resources.py): `app/application/routers/manage_resources.py`
- [Category management](https://github.com/robungid/stashify/blob/main/app/application/routers/manage_categories.py): `app/application/routers/manage_categories.py`
- [Quiz management](https://github.com/robungid/stashify/blob/main/app/application/routers/manage_quizes.py): `app/application/routers/manage_quizes.py`
- [User management](https://github.com/robungid/stashify/blob/main/app/application/routers/manage_users.py): `app/application/routers/manage_users.py`
- [Main menu](https://github.com/robungid/stashify/blob/main/app/application/routers/menu.py): `app/application/routers/menu.py`

### Resource and quiz domain

- [Resource entities](https://github.com/robungid/stashify/blob/main/app/domain/entities/resource_item.py): `app/domain/entities/resource_item.py`
- [Category entities](https://github.com/robungid/stashify/blob/main/app/domain/entities/category_item.py): `app/domain/entities/category_item.py`
- [Quiz entities](https://github.com/robungid/stashify/blob/main/app/domain/entities/quiz_question.py): `app/domain/entities/quiz_question.py`
- [Repository contracts](https://github.com/robungid/stashify/blob/main/app/domain/repositories/resource_item.py): `app/domain/repositories/resource_item.py`

### Application services

- [Resource service](https://github.com/robungid/stashify/blob/main/app/application/services/resource_item.py): `app/application/services/resource_item.py`
- [Service providers](https://github.com/robungid/stashify/blob/main/app/application/containers/providers/services.py): `app/application/containers/providers/services.py`

### SQL persistence

- [Resource SQL repository](https://github.com/robungid/stashify/blob/main/app/infrastructure/repositories/sql/resource_item.py): `app/infrastructure/repositories/sql/resource_item.py`
- [Resource mapper](https://github.com/robungid/stashify/blob/main/app/infrastructure/mappers/resource_item.py): `app/infrastructure/mappers/resource_item.py`
- [Resource table model](https://github.com/robungid/stashify/blob/main/app/infrastructure/models/resource_item.py): `app/infrastructure/models/resource_item.py`
- [Category SQL repository](https://github.com/robungid/stashify/blob/main/app/infrastructure/repositories/sql/category_item.py): `app/infrastructure/repositories/sql/category_item.py`
- [Database setup](https://github.com/robungid/stashify/blob/main/app/database/init.py): `app/database/init.py`

### Other components

- **Telegram user**
- **PostgreSQL**

## Connections

- Telegram user → Bot runtime: sends updates
- Bot runtime → Resource search: registers router (evidence: `app/main.py`)
- Bot runtime → Resource browsing: registers router (evidence: `app/main.py`)
- Bot runtime → Resource management: registers router (evidence: `app/main.py`)
- Bot runtime → Category management: registers router (evidence: `app/main.py`)
- Bot runtime → Quiz management: registers router (evidence: `app/main.py`)
- Bot runtime → User management: registers router (evidence: `app/main.py`)
- Bot runtime → Main menu: registers router (evidence: `app/main.py`)
- Resource search → Resource service: queries resources (evidence: `app/application/routers/search_resource.py`)
- Resource service → Repository contracts: uses contract (evidence: `app/application/services/resource_item.py`)
- Service providers → Resource service: provides service (evidence: `app/application/containers/providers/services.py`)
- Resource SQL repository → Repository contracts: implements contract (evidence: `app/infrastructure/repositories/sql/resource_item.py`)
- Resource SQL repository → Resource mapper: maps records (evidence: `app/infrastructure/repositories/sql/resource_item.py`)
- Resource mapper → Resource table model: converts model (evidence: `app/infrastructure/mappers/resource_item.py`)
- Category SQL repository → Category entities: maps categories (evidence: `app/infrastructure/repositories/sql/category_item.py`)
- Bot runtime → Database setup: initializes models (evidence: `app/main.py`)
- Database setup → PostgreSQL: uses database
- Resource browsing → Resource service: queries resources
- Resource management → Resource service: manages resources (evidence: `app/application/routers/manage_resources.py`)
- Category management → Category SQL repository: persists categories
- Quiz management → Quiz entities: manages quizzes
- User management → Bot runtime: administers users (evidence: `app/main.py`)
- Resource table model → PostgreSQL: stored in
