# mclowam/structured_knowledge architecture

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

- Interactive diagram: https://gitdiagram.com/mclowam/structured_knowledge
- Repository: https://github.com/mclowam/structured_knowledge

## Overview

This repository implements a knowledge-library product: users authenticate, create knowledge collections, add files or URLs, and retrieve extracted or compressed content. The frontend exposes login and knowledge/library views; backend services handle identity and collection management, while a worker processes pending and extracted libraries. The payment service has no evidenced runtime behavior in the supplied material, so it is omitted. Connections reflect shown calls or indexed imports; where frontend-to-backend wiring is not evidenced, no connection is asserted.

Main entry points: [`frontend/src/app/App.tsx`](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/app/App.tsx) (App routes), [`backend/library/app/api/library.py`](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/api/library.py) (Knowledge routes), [`backend/library/app/worker.py`](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/worker.py) (Processing worker), [`backend/auth/app/api/users.py`](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/api/users.py) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routes<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_knowledge_pages["Knowledge pages"]
  node_library_page["Library detail"]
  node_auth_context["Auth context<br/>[AuthContext.tsx]"]
  node_auth_client["Auth API<br/>[auth.ts]"]
  node_library_api["Library API<br/>[library.ts]"]
end

subgraph group_identity["Identity service"]
  node_auth_api["Auth routes<br/>[users.py]"]
  node_auth_usecases["Auth wiring<br/>[users.py]"]
  node_auth_services["Auth services<br/>[users.py]"]
  node_login_service["Login and refresh<br/>[login.py]"]
  node_token_provider["JWT provider<br/>[token.py]"]
  node_auth_guard["Token guard<br/>[deps.py]"]
end

subgraph group_library["Knowledge library"]
  node_knowledge_api["Knowledge routes<br/>[library.py]"]
  node_knowledge_service["Knowledge service<br/>[knowledge.py]"]
  node_library_service["Library service<br/>[library.py]"]
  node_extract_dispatch["Source dispatcher<br/>[dispatcher.py]"]
  node_worker["Processing worker<br/>[worker.py]"]
  node_extraction_case["Extraction use case<br/>[extraction.py]"]
  node_compression_case["Compression use case<br/>[compression.py]"]
  node_compression_agent["Compression agent<br/>[compression.py]"]
end

subgraph group_storage["Persistence"]
  node_document_storage["Document storage"]
  node_object_store[("S3-compatible store")]
  node_library_repo["Library repository<br/>[library.py]"]
  node_user_repo["User repository<br/>[users.py]"]
  node_relational_db[("PostgreSQL")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_knowledge_pages
node_app -->|"routes to"| node_library_page
node_app -->|"provides"| node_auth_context
node_auth_context -->|"calls"| node_auth_client
node_user -.->|"authenticates"| node_auth_api
node_auth_api -->|"resolves services"| node_auth_usecases
node_auth_api -->|"checks identity"| node_auth_guard
node_auth_usecases -->|"builds repository"| node_user_repo
node_auth_usecases -->|"builds services"| node_login_service
node_login_service -->|"creates tokens"| node_token_provider
node_auth_guard -->|"decodes tokens"| node_token_provider
node_user_repo -->|"reads and writes"| node_relational_db
node_user -.->|"manages collections"| node_knowledge_api
node_knowledge_api -->|"calls"| node_knowledge_service
node_knowledge_api -->|"calls"| node_library_service
node_knowledge_api -->|"checks file type"| node_extract_dispatch
node_library_service -->|"uses"| node_knowledge_service
node_library_service -->|"uses"| node_document_storage
node_document_storage -->|"uploads and reads"| node_object_store
node_worker -->|"lists and loads"| node_library_repo
node_worker -->|"builds for pending"| node_extraction_case
node_worker -->|"builds for extracted"| node_compression_case
node_extraction_case -->|"dispatches extraction"| node_extract_dispatch
node_compression_case -.->|"uses"| node_compression_agent
node_library_repo -->|"reads and writes"| node_relational_db
node_knowledge_pages -.->|"fetches data"| node_library_api
node_library_page -.->|"fetches data"| node_library_api

click node_app "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/app/App.tsx"
click node_login "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/LoginPage.tsx"
click node_knowledge_pages "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/KnowledgeListPage.tsx"
click node_library_page "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/LibraryDetailPage.tsx"
click node_auth_context "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/auth/AuthContext.tsx"
click node_auth_client "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/api/auth.ts"
click node_library_api "https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/api/library.ts"
click node_auth_api "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/api/users.py"
click node_auth_usecases "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/use_cases/users.py"
click node_auth_services "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/services/users.py"
click node_login_service "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/services/login.py"
click node_token_provider "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/core/security/token.py"
click node_auth_guard "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/core/security/deps.py"
click node_knowledge_api "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/api/library.py"
click node_knowledge_service "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/services/knowledge.py"
click node_library_service "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/services/library.py"
click node_extract_dispatch "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/repositories/extractors/dispatcher.py"
click node_worker "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/worker.py"
click node_extraction_case "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/use_cases/extraction.py"
click node_compression_case "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/use_cases/compression.py"
click node_compression_agent "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/agents/compression.py"
click node_document_storage "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/storage/document_storage.py"
click node_library_repo "https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/repositories/library.py"
click node_user_repo "https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/repositories/users.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_app,node_login,node_knowledge_pages,node_library_page,node_auth_context,node_auth_client,node_library_api,node_user toneBlue
class node_auth_api,node_auth_usecases,node_auth_services,node_login_service,node_token_provider,node_auth_guard toneAmber
class node_knowledge_api,node_knowledge_service,node_library_service,node_extract_dispatch,node_worker,node_extraction_case,node_compression_case,node_compression_agent toneMint
class node_document_storage,node_object_store,node_library_repo,node_user_repo,node_relational_db toneRose
```

## Components

### Web client

- [App routes](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Login page](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Knowledge pages](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/KnowledgeListPage.tsx): `frontend/src/pages/KnowledgeListPage.tsx`
- [Library detail](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/pages/LibraryDetailPage.tsx): `frontend/src/pages/LibraryDetailPage.tsx`
- [Auth context](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/auth/AuthContext.tsx): `frontend/src/auth/AuthContext.tsx`
- [Auth API](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/api/auth.ts): `frontend/src/api/auth.ts`
- [Library API](https://github.com/mclowam/structured_knowledge/blob/main/frontend/src/api/library.ts): `frontend/src/api/library.ts`

### Identity service

- [Auth routes](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/api/users.py): `backend/auth/app/api/users.py`
- [Auth wiring](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/use_cases/users.py): `backend/auth/app/use_cases/users.py`
- [Auth services](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/services/users.py): `backend/auth/app/services/users.py`
- [Login and refresh](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/services/login.py): `backend/auth/app/services/login.py`
- [JWT provider](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/core/security/token.py): `backend/auth/app/core/security/token.py`
- [Token guard](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/core/security/deps.py): `backend/auth/app/core/security/deps.py`

### Knowledge library

- [Knowledge routes](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/api/library.py): `backend/library/app/api/library.py`
- [Knowledge service](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/services/knowledge.py): `backend/library/app/services/knowledge.py`
- [Library service](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/services/library.py): `backend/library/app/services/library.py`
- [Source dispatcher](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/repositories/extractors/dispatcher.py): `backend/library/app/repositories/extractors/dispatcher.py`
- [Processing worker](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/worker.py): `backend/library/app/worker.py`
- [Extraction use case](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/use_cases/extraction.py): `backend/library/app/use_cases/extraction.py`
- [Compression use case](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/use_cases/compression.py): `backend/library/app/use_cases/compression.py`
- [Compression agent](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/agents/compression.py): `backend/library/app/agents/compression.py`

### Persistence

- [Document storage](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/storage/document_storage.py): `backend/library/app/storage/document_storage.py`
- **S3-compatible store**
- [Library repository](https://github.com/mclowam/structured_knowledge/blob/main/backend/library/app/repositories/library.py): `backend/library/app/repositories/library.py`
- [User repository](https://github.com/mclowam/structured_knowledge/blob/main/backend/auth/app/repositories/users.py): `backend/auth/app/repositories/users.py`
- **PostgreSQL**

### Other components

- **User**

## Connections

- User → App routes: uses (evidence: `frontend/src/app/App.tsx`)
- App routes → Login page: routes to (evidence: `frontend/src/app/App.tsx`)
- App routes → Knowledge pages: routes to (evidence: `frontend/src/app/App.tsx`)
- App routes → Library detail: routes to (evidence: `frontend/src/app/App.tsx`)
- App routes → Auth context: provides (evidence: `frontend/src/app/App.tsx`)
- Auth context → Auth API: calls (evidence: `frontend/src/auth/AuthContext.tsx`)
- User → Auth routes: authenticates
- Auth routes → Auth wiring: resolves services (evidence: `backend/auth/app/api/users.py`)
- Auth routes → Token guard: checks identity (evidence: `backend/auth/app/api/users.py`)
- Auth wiring → User repository: builds repository (evidence: `backend/auth/app/use_cases/users.py`)
- Auth wiring → Login and refresh: builds services (evidence: `backend/auth/app/use_cases/users.py`)
- Login and refresh → JWT provider: creates tokens (evidence: `backend/auth/app/services/login.py`)
- Token guard → JWT provider: decodes tokens (evidence: `backend/auth/app/core/security/deps.py`)
- User repository → PostgreSQL: reads and writes (evidence: `backend/auth/app/repositories/users.py`)
- User → Knowledge routes: manages collections
- Knowledge routes → Knowledge service: calls (evidence: `backend/library/app/api/library.py`)
- Knowledge routes → Library service: calls (evidence: `backend/library/app/api/library.py`)
- Knowledge routes → Source dispatcher: checks file type (evidence: `backend/library/app/api/library.py`)
- Library service → Knowledge service: uses (evidence: `backend/library/app/services/library.py`)
- Library service → Document storage: uses (evidence: `backend/library/app/services/library.py`)
- Document storage → S3-compatible store: uploads and reads (evidence: `backend/library/app/storage/document_storage.py`)
- Processing worker → Library repository: lists and loads (evidence: `backend/library/app/worker.py`)
- Processing worker → Extraction use case: builds for pending (evidence: `backend/library/app/worker.py`)
- Processing worker → Compression use case: builds for extracted (evidence: `backend/library/app/worker.py`)
- Extraction use case → Source dispatcher: dispatches extraction (evidence: `backend/library/app/use_cases/extraction.py`)
- Compression use case → Compression agent: uses
- Library repository → PostgreSQL: reads and writes (evidence: `backend/library/app/repositories/library.py`)
- Knowledge pages → Library API: fetches data
- Library detail → Library API: fetches data
