# psharpx/python-labs architecture

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

- Interactive diagram: https://gitdiagram.com/psharpx/python-labs
- Repository: https://github.com/psharpx/python-labs

## Overview

This tree is a collection of independent Python applications, not one integrated product. The most developed workflow is TechDoc Builder: a user submits a request, the agent coordinates analysis and pauses for clarification or financial approval; catalog, tariff and graph-context capabilities are provided by a separate MCP application. The tree also contains a bookstore API, a product-review RAG scraper, and smaller agent projects. Relationships are shown only where excerpts or the source index support them; several unsampled workflow internals are therefore left unconnected.

Main entry points: [`techdoc-agent/src/workflow.py`](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/workflow.py) (Workflow engine), [`techdoc-agent/main.py`](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/main.py) (Builder CLI), [`techdoc-mcp/src/catalog/services/product_service_service.py`](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/services/product_service_service.py) (Catalog service), [`techdoc-mcp/src/catalog/graph/services/graph_rag_service.py`](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/graph/services/graph_rag_service.py) (Graph context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_techdoc["TechDoc Builder"]
  node_builder_cli["Builder CLI<br/>[main.py]"]
  node_workflow["Workflow engine<br/>[workflow.py]"]
  node_routing["Stage routing<br/>[routing.py]"]
  node_requirements_agent["Requirements agent<br/>[state_manager.py]"]
  node_requirement_inputs["Requirement schemas"]
  node_shared_models["Shared models<br/>[models.py]"]
  node_shared_reducers["State reducers<br/>[reducers.py]"]
  node_logging["Agent logging<br/>[logging.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_architect_tools["Architecture tools"]
  node_mcp_clients["MCP clients"]
end

subgraph group_catalog["TechDoc Catalog MCP"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_catalog_service["Catalog service"]
  node_catalog_domain["Catalog DTOs<br/>[product_service.py]"]
  node_tariff_service["Tariff calculation"]
  node_graph_service["Graph context"]
  node_graph_domain["Graph DTOs"]
  node_catalog_db[("Catalog database<br/>[database.py]")]
  node_catalog_main["MCP app entry<br/>[main.py]"]
end

subgraph group_bookstore["Bookstore API"]
  node_book_api["Book API routes<br/>[book_router.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_book_repo_impl["Author repository"]
  node_book_repo_port["Repository ports"]
  node_book_models["Database models"]
  node_outbox_worker["Outbox worker<br/>[outbox_worker.py]"]
  node_outbox_handler["Outbox handler<br/>[handler.py]"]
end

subgraph group_scraper["Review Scraper"]
  node_scraper_main["Scraper entry<br/>[main.py]"]
  node_rag_stages["Index and retrieve<br/>[rag.py]"]
  node_review_agent["Review agent<br/>[agent.py]"]
end

subgraph group_campaign["Campaign Agent"]
end

subgraph group_other["Other Agents"]
end

node_user(("User"))
node_neo4j[("Neo4j")]
node_sql_db[("SQL database")]
node_book_user(("Bookstore client"))
node_review_user(("Review researcher"))

node_user -->|"submits request"| node_builder_cli
node_builder_cli -.->|"starts and resumes"| node_workflow
node_builder_cli -->|"requests input"| node_user
node_workflow -.->|"routes stages"| node_routing
node_workflow -.->|"runs analysis"| node_requirements_agent
node_requirements_agent -->|"validates inputs"| node_requirement_inputs
node_requirements_agent -->|"updates state"| node_shared_models
node_builder_cli -->|"handles responses"| node_shared_models
node_workflow -.->|"combines state"| node_shared_reducers
node_workflow -.->|"emits logs"| node_logging
node_workflow -.->|"applies checks"| node_guardrails
node_workflow -.->|"uses tools"| node_architect_tools
node_workflow -.->|"uses clients"| node_mcp_clients
node_catalog_main -->|"fetches catalog"| node_catalog_service
node_catalog_main -->|"calculates tariff"| node_tariff_service
node_catalog_main -->|"fetches graph context"| node_graph_service
node_mcp_tools -->|"registers capability"| node_catalog_service
node_mcp_tools -->|"registers capability"| node_tariff_service
node_mcp_tools -->|"registers capability"| node_graph_service
node_catalog_service -->|"maps results"| node_catalog_domain
node_catalog_service -->|"opens session"| node_catalog_db
node_tariff_service -->|"reads rates"| node_catalog_db
node_graph_service -->|"builds DTOs"| node_graph_domain
node_graph_service -->|"queries graph"| node_neo4j
node_catalog_db -->|"connects"| node_sql_db
node_book_user -.->|"calls API"| node_api_router
node_api_router -->|"routes requests"| node_book_api
node_book_repo_impl -->|"implements port"| node_book_repo_port
node_book_repo_impl -->|"persists records"| node_book_models
node_outbox_worker -->|"invokes handler"| node_outbox_handler
node_review_user -->|"starts research"| node_scraper_main
node_scraper_main -->|"indexes and retrieves"| node_rag_stages
node_scraper_main -->|"starts agent"| node_review_agent
node_review_agent -.->|"searches reviews"| node_rag_stages

click node_builder_cli "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/main.py"
click node_workflow "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/workflow.py"
click node_routing "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/routing.py"
click node_requirements_agent "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/tools/requirements/state_manager.py"
click node_requirement_inputs "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/tools/requirements/state_manager_input.py"
click node_shared_models "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/shared/models.py"
click node_shared_reducers "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/shared/reducers.py"
click node_logging "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/middlewares/logging.py"
click node_guardrails "https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/middlewares/guardrails.py"
click node_architect_tools "https://github.com/psharpx/python-labs/tree/main/techdoc-agent/src/tools/architect"
click node_mcp_clients "https://github.com/psharpx/python-labs/tree/main/techdoc-agent/src/tools/mcp"
click node_mcp_tools "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/tools.py"
click node_catalog_service "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/services/product_service_service.py"
click node_catalog_domain "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/domain/product_service.py"
click node_tariff_service "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/services/tariff_calculation_service.py"
click node_graph_service "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/graph/services/graph_rag_service.py"
click node_graph_domain "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/graph/domain/graph_rag_domain.py"
click node_catalog_db "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/database.py"
click node_catalog_main "https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/main.py"
click node_book_api "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/api/v1/routes/book_router.py"
click node_api_router "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/api/v1/router.py"
click node_book_repo_impl "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/infrastructure/repositories/author_repository_impl.py"
click node_book_repo_port "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/application/ports/repositories/author_repository.py"
click node_book_models "https://github.com/psharpx/python-labs/tree/main/fastapi-bookstore/app/infrastructure/database/models"
click node_outbox_worker "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/workers/outbox_worker.py"
click node_outbox_handler "https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/application/use_cases/process_outbox/handler.py"
click node_scraper_main "https://github.com/psharpx/python-labs/blob/main/smarty-scraper/main.py"
click node_rag_stages "https://github.com/psharpx/python-labs/blob/main/smarty-scraper/rag.py"
click node_review_agent "https://github.com/psharpx/python-labs/blob/main/smarty-scraper/agent.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_builder_cli,node_workflow,node_routing,node_requirements_agent,node_requirement_inputs,node_shared_models,node_shared_reducers,node_logging,node_guardrails,node_architect_tools,node_mcp_clients,node_user,node_book_user,node_review_user toneBlue
class node_mcp_tools,node_catalog_service,node_catalog_domain,node_tariff_service,node_graph_service,node_graph_domain,node_catalog_db,node_catalog_main,node_neo4j,node_sql_db toneAmber
class node_book_api,node_api_router,node_book_repo_impl,node_book_repo_port,node_book_models,node_outbox_worker,node_outbox_handler toneMint
class node_scraper_main,node_rag_stages,node_review_agent toneRose
```

## Components

### TechDoc Builder

- [Builder CLI](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/main.py): `techdoc-agent/main.py`
- [Workflow engine](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/workflow.py): `techdoc-agent/src/workflow.py`
- [Stage routing](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/routing.py): `techdoc-agent/src/routing.py`
- [Requirements agent](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/tools/requirements/state_manager.py): `techdoc-agent/src/tools/requirements/state_manager.py`
- [Requirement schemas](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/tools/requirements/state_manager_input.py): `techdoc-agent/src/tools/requirements/state_manager_input.py`
- [Shared models](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/shared/models.py): `techdoc-agent/src/shared/models.py`
- [State reducers](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/shared/reducers.py): `techdoc-agent/src/shared/reducers.py`
- [Agent logging](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/middlewares/logging.py): `techdoc-agent/src/middlewares/logging.py`
- [Guardrails](https://github.com/psharpx/python-labs/blob/main/techdoc-agent/src/middlewares/guardrails.py): `techdoc-agent/src/middlewares/guardrails.py`
- [Architecture tools](https://github.com/psharpx/python-labs/tree/main/techdoc-agent/src/tools/architect): `techdoc-agent/src/tools/architect`
- [MCP clients](https://github.com/psharpx/python-labs/tree/main/techdoc-agent/src/tools/mcp): `techdoc-agent/src/tools/mcp`

### TechDoc Catalog MCP

- [MCP tools](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/tools.py): `techdoc-mcp/tools.py`
- [Catalog service](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/services/product_service_service.py): `techdoc-mcp/src/catalog/services/product_service_service.py`
- [Catalog DTOs](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/domain/product_service.py): `techdoc-mcp/src/catalog/domain/product_service.py`
- [Tariff calculation](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/services/tariff_calculation_service.py): `techdoc-mcp/src/catalog/services/tariff_calculation_service.py`
- [Graph context](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/graph/services/graph_rag_service.py): `techdoc-mcp/src/catalog/graph/services/graph_rag_service.py`
- [Graph DTOs](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/graph/domain/graph_rag_domain.py): `techdoc-mcp/src/catalog/graph/domain/graph_rag_domain.py`
- [Catalog database](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/src/catalog/database.py): `techdoc-mcp/src/catalog/database.py`
- [MCP app entry](https://github.com/psharpx/python-labs/blob/main/techdoc-mcp/main.py): `techdoc-mcp/main.py`

### Bookstore API

- [Book API routes](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/api/v1/routes/book_router.py): `fastapi-bookstore/app/api/v1/routes/book_router.py`
- [API router](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/api/v1/router.py): `fastapi-bookstore/app/api/v1/router.py`
- [Author repository](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/infrastructure/repositories/author_repository_impl.py): `fastapi-bookstore/app/infrastructure/repositories/author_repository_impl.py`
- [Repository ports](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/application/ports/repositories/author_repository.py): `fastapi-bookstore/app/application/ports/repositories/author_repository.py`
- [Database models](https://github.com/psharpx/python-labs/tree/main/fastapi-bookstore/app/infrastructure/database/models): `fastapi-bookstore/app/infrastructure/database/models`
- [Outbox worker](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/workers/outbox_worker.py): `fastapi-bookstore/app/workers/outbox_worker.py`
- [Outbox handler](https://github.com/psharpx/python-labs/blob/main/fastapi-bookstore/app/application/use_cases/process_outbox/handler.py): `fastapi-bookstore/app/application/use_cases/process_outbox/handler.py`

### Review Scraper

- [Scraper entry](https://github.com/psharpx/python-labs/blob/main/smarty-scraper/main.py): `smarty-scraper/main.py`
- [Index and retrieve](https://github.com/psharpx/python-labs/blob/main/smarty-scraper/rag.py): `smarty-scraper/rag.py`
- [Review agent](https://github.com/psharpx/python-labs/blob/main/smarty-scraper/agent.py): `smarty-scraper/agent.py`

### Other components

- **User**
- **Neo4j**
- **SQL database**
- **Bookstore client**
- **Review researcher**

## Connections

- User → Builder CLI: submits request (evidence: `techdoc-agent/main.py`)
- Builder CLI → Workflow engine: starts and resumes
- Builder CLI → User: requests input (evidence: `techdoc-agent/main.py`)
- Workflow engine → Stage routing: routes stages
- Workflow engine → Requirements agent: runs analysis
- Requirements agent → Requirement schemas: validates inputs (evidence: `techdoc-agent/src/tools/requirements/state_manager.py`)
- Requirements agent → Shared models: updates state (evidence: `techdoc-agent/src/tools/requirements/state_manager.py`)
- Builder CLI → Shared models: handles responses (evidence: `techdoc-agent/main.py`)
- Workflow engine → State reducers: combines state
- Workflow engine → Agent logging: emits logs
- Workflow engine → Guardrails: applies checks
- Workflow engine → Architecture tools: uses tools
- Workflow engine → MCP clients: uses clients
- MCP app entry → Catalog service: fetches catalog (evidence: `techdoc-mcp/main.py`)
- MCP app entry → Tariff calculation: calculates tariff (evidence: `techdoc-mcp/main.py`)
- MCP app entry → Graph context: fetches graph context (evidence: `techdoc-mcp/main.py`)
- MCP tools → Catalog service: registers capability (evidence: `techdoc-mcp/tools.py`)
- MCP tools → Tariff calculation: registers capability (evidence: `techdoc-mcp/tools.py`)
- MCP tools → Graph context: registers capability (evidence: `techdoc-mcp/tools.py`)
- Catalog service → Catalog DTOs: maps results (evidence: `techdoc-mcp/src/catalog/services/product_service_service.py`)
- Catalog service → Catalog database: opens session (evidence: `techdoc-mcp/src/catalog/services/product_service_service.py`)
- Tariff calculation → Catalog database: reads rates (evidence: `techdoc-mcp/src/catalog/services/tariff_calculation_service.py`)
- Graph context → Graph DTOs: builds DTOs (evidence: `techdoc-mcp/src/catalog/graph/services/graph_rag_service.py`)
- Graph context → Neo4j: queries graph (evidence: `techdoc-mcp/src/catalog/graph/services/graph_rag_service.py`)
- Catalog database → SQL database: connects (evidence: `techdoc-mcp/src/catalog/database.py`)
- Bookstore client → API router: calls API
- API router → Book API routes: routes requests (evidence: `fastapi-bookstore/app/api/v1/router.py`)
- Author repository → Repository ports: implements port (evidence: `fastapi-bookstore/app/infrastructure/repositories/author_repository_impl.py`)
- Author repository → Database models: persists records (evidence: `fastapi-bookstore/app/infrastructure/repositories/author_repository_impl.py`)
- Outbox worker → Outbox handler: invokes handler (evidence: `fastapi-bookstore/app/workers/outbox_worker.py`)
- Review researcher → Scraper entry: starts research (evidence: `smarty-scraper/main.py`)
- Scraper entry → Index and retrieve: indexes and retrieves (evidence: `smarty-scraper/main.py`)
- Scraper entry → Review agent: starts agent (evidence: `smarty-scraper/main.py`)
- Review agent → Index and retrieve: searches reviews
