# maintainer64/skills-search-tram architecture

> Architecture diagram of the GitHub repository maintainer64/skills-search-tram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maintainer64/skills-search-tram
- Repository: https://github.com/maintainer64/skills-search-tram

## Overview

##### Project Type and Purpose
- This is a voice‐assistant skill (“Навык для умных устройств”) built on Python 3.12, deployed as a Yandex Serverless function.
- Its purpose is to accept user requests via Yandex Dialogs, determine the nearest public‐transport schedule using DoubleGIS APIs, and respond through the voice interface.

##### High‐Level Architecture
- The system lives entirely inside a single Serverless Function, logically divided into layers:
a. EntryPoint (yandex_serverless.handler)
b. Dependency Injection Container
c. Handlers (intent dispatch, state management)
d. Services (business logic)
e. Clients (external DoubleGIS API calls)
f. External Service (DoubleGIS)

##### Main Components & Their Relationships
- Yandex Dialogs Platform
- Receives user voice input → transcribes to intent JSON → invokes your function over HTTP.
- Serverless Function (application/yandex_serverless.py)
- handler(event, context) is the entrypoint.
- Loads configuration (application/config.py + env vars).
- Instantiates the DI container (application/container/container.py).
- Routes the incoming intent to the correct Handler.
- Handlers Layer (application/handlers)
- intents.py defines intent IDs (CONFIRM, REJECT, etc.).
- states.py defines conversational states.
- handlers.py maps intents & states to business‐logic calls.
- Services Layer (application/services)
- address_to_geo_service_double_gis.py implements geocoding via DoubleGIS.
- search_schedule_service_double_gis.py implements schedule lookup.
- language.py handles localization or text formatting.
- Abstract interfaces (e.g., address_to_geo_service_abs.py) ensure easy swapping.
- Clients Layer (application/clients/doublegis)
- base/client.py: shared HTTP client config.
- routings, suggests, webapi submodules define REST endpoints + data models.
- utils.py contains common helpers (e.g., parameter building, error handling).
- External DoubleGIS API
- Receives HTTP requests from Clients → returns JSON responses.

##### Data Flow
1. User speaks → Yandex Dialogs → HTTP JSON request.
2. Serverless handler parses the event → calls DI container to get Handler instance.
3. Handler consults Services, passing user slots & session state.
4. Service calls appropriate Client module → issues HTTP to DoubleGIS.
5. DoubleGIS responds → Client parses into Python models.
6. Service transforms models into user‐friendly text.
7. Handler packs the response into Yandex Dialogs JSON format.
8. Function returns JSON → Yandex speaks the reply.

##### Architectural Patterns & Principles
- Layered/Clean Architecture: Handlers → Services → Clients → External API
- Dependency Injection for easy testing and swapping of service implementations.
- Separation of concerns:
- Clients do only external communication & model mapping.
- Services encapsulate business rules.
- Handlers orchestrate conversation flow.

##### What to Label and Emphasize
- Each layer’s name and primary modules/files.
- Entrypoint signature `handler(event, context)` and env var loading.
- DI container supplies concrete implementations for abstract services.
- That scheduling logic lives in `search_schedule_service_double_gis.py`, and geocoding in `address_to_geo_service_double_gis.py`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    YDialog["Yandex Dialogs Platform"]:::external
    DoubleGIS["DoubleGIS REST API"]:::external

    %% Configuration
    Config[(Config)]:::config

    %% Serverless Function Container
    subgraph "Serverless Function"
        EntryPoint["yandex_serverless.handler(event, context)"]:::blue
        DI["DI Container"]:::blue

        subgraph "Handlers Layer"
            Intents["intents.py"]:::blue
            States["states.py"]:::blue
            HandlersMod["handlers.py"]:::blue
        end

        subgraph "Services Layer"
            GeoAbs["address_to_geo_service_abs.py"]:::blue
            GeoImpl["address_to_geo_service_double_gis.py"]:::blue
            SchedAbs["search_schedule_service.py"]:::blue
            SchedImpl["search_schedule_service_double_gis.py"]:::blue
            Lang["language.py"]:::blue
        end

        subgraph "Clients Layer"
            ClientBase["client.py"]:::blue
            RouteClient["routings client.py"]:::blue
            RouteModels["routings models.py"]:::blue
            SuggestClient["suggests client.py"]:::blue
            SuggestModels["suggests models.py"]:::blue
            WebClient["webapi client.py"]:::blue
            WebModels["webapi models.py"]:::blue
            Utils["utils.py"]:::blue
        end
    end

    %% Data Flow
    YDialog -->|"invoke with intent JSON"| EntryPoint
    Config -->|"load env vars"| EntryPoint
    EntryPoint -->|"instantiate"| DI
    DI -->|"resolve Handler"| HandlersMod
    HandlersMod -->|"addressToGeo()"| GeoImpl
    HandlersMod -->|"getSchedule()"| SchedImpl
    GeoImpl -->|"uses abstract"| GeoAbs
    SchedImpl -->|"uses abstract"| SchedAbs
    GeoImpl -->|"call /suggests"| SuggestClient
    SchedImpl -->|"call /routings"| RouteClient
    SuggestClient -->|"HTTP request/response"| DoubleGIS
    RouteClient -->|"HTTP request/response"| DoubleGIS
    DoubleGIS -->|"JSON response"| SuggestClient
    DoubleGIS -->|"JSON response"| RouteClient
    SuggestClient -->|"models"| GeoImpl
    RouteClient -->|"models"| SchedImpl
    GeoImpl -->|"format text"| Lang
    SchedImpl -->|"format text"| Lang
    GeoImpl -->|"return result"| HandlersMod
    SchedImpl -->|"return result"| HandlersMod
    HandlersMod -->|"build response JSON"| EntryPoint
    EntryPoint -->|"return JSON"| YDialog

    %% Click Events
    click EntryPoint "https://github.com/maintainer64/skills-search-tram/blob/master/application/yandex_serverless.py"
    click Config "https://github.com/maintainer64/skills-search-tram/blob/master/application/config.py"
    click DI "https://github.com/maintainer64/skills-search-tram/blob/master/application/container/container.py"
    click Intents "https://github.com/maintainer64/skills-search-tram/blob/master/application/handlers/intents.py"
    click States "https://github.com/maintainer64/skills-search-tram/blob/master/application/handlers/states.py"
    click HandlersMod "https://github.com/maintainer64/skills-search-tram/blob/master/application/handlers/handlers.py"
    click GeoAbs "https://github.com/maintainer64/skills-search-tram/blob/master/application/services/address_to_geo_service_abs.py"
    click GeoImpl "https://github.com/maintainer64/skills-search-tram/blob/master/application/services/address_to_geo_service_double_gis.py"
    click SchedAbs "https://github.com/maintainer64/skills-search-tram/blob/master/application/services/search_schedule_service.py"
    click SchedImpl "https://github.com/maintainer64/skills-search-tram/blob/master/application/services/search_schedule_service_double_gis.py"
    click Lang "https://github.com/maintainer64/skills-search-tram/blob/master/application/services/language.py"
    click ClientBase "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/base/client.py"
    click RouteClient "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/routings/client.py"
    click RouteModels "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/routings/models.py"
    click SuggestClient "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/suggests/client.py"
    click SuggestModels "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/suggests/models.py"
    click WebClient "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/webapi/client.py"
    click WebModels "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/webapi/models.py"
    click Utils "https://github.com/maintainer64/skills-search-tram/blob/master/application/clients/doublegis/utils.py"

    %% Styles
    classDef blue fill:#9BC2E6,stroke:#000,stroke-width:1px
    classDef external fill:#FFE599,stroke:#000,stroke-width:1px
    classDef config fill:#B6D7A8,stroke:#000,stroke-width:1px
```
