# hynek/svcs architecture

> Architecture diagram of the GitHub repository hynek/svcs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hynek/svcs
- Repository: https://github.com/hynek/svcs

## Overview

##### Main Components

a) Core Service Container:
- Registry and Container components (from _core.py)
- Factory management system

b) Framework Integrations Layer:
- AIOHTTP
- FastAPI
- Flask
- Pyramid
- Starlette
- How each framework connects to the core container

c) Service Management Components:
- Health Check System
- Cleanup Management
- Type Safety Layer

##### Relationships to Illustrate

a) Service Registration Flow:
- How services are registered with factories
- Type registration paths

b) Service Resolution Flow:
- Demonstrate how services are resolved from requests
- Lifecycle management

**┌─────────────────────────────────────┐**
- Client Application        │
- ┘
- ↓               ↑
**┌─────────────────────────────────────┐**
- Framework Integration Layer    │
- ┌─────┐  ┌─────┐  ┌─────┐  ┌────┐ │
- Flask│  │FastAPI│ │AIOHTTP│ │...│ │
- ┘  └─────┘  └─────┘  └────┘ │
- ┘
- ↓               ↑
**┌─────────────────────────────────────┐**
- Core Container              │
- ┌─────────────┐   ┌────────────┐  │
- Registry  │←→ │  Factory   │  │
- ┘   └────────────┘  │
- ┌─────────────┐   ┌────────────┐  │
- Type Safety  │   │  Cleanup   │  │
- ┘   └────────────┘  │
- ┘
- ↓               ↑
**┌─────────────────────────────────────┐**
- Service Instances           │
- ┘

##### Important Details to Capture

a) Type Safety Layer:
- How static typing is supported but optional
- Type forwarding to type checkers

b) Context Management:
- Automatic cleanup flows
- How context managers are handled

c) Health Check System:
- Monitoring and introspection paths
- Health check integration points

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Application"]
        CA[Client Code]
    end

    subgraph Frameworks["Framework Integration Layer"]
        direction TB
        AIO["AIOHTTP"]:::framework
        FAST["FastAPI"]:::framework
        FLASK["Flask"]:::framework
        PYR["Pyramid"]:::framework
        STAR["Starlette"]:::framework
    end

    subgraph Core["Core Container"]
        direction TB
        REG["Registry"]:::core
        FAC["Factory"]:::core
        TS["Type Safety"]:::core
        CM["Cleanup Management"]:::core
        EH["Exception Handler"]:::core
    end

    subgraph Services["Service Instances"]
        SI[("Service Instances")]:::service
    end

    subgraph Health["Health Check System"]
        direction TB
        AIO_H["AIOHTTP Health"]:::health
        FAST_H["FastAPI Health"]:::health
        FLASK_H["Flask Health"]:::health
        PYR_H["Pyramid Health"]:::health
        STAR_H["Starlette Health"]:::health
    end

    CA --> Frameworks
    Frameworks --> Core
    Core --> Services
    Core --> Health

    %% Component relationships
    REG <--> FAC
    REG --> TS
    REG --> CM
    REG --> EH

    %% Framework to Health relationships
    AIO --> AIO_H
    FAST --> FAST_H
    FLASK --> FLASK_H
    PYR --> PYR_H
    STAR --> STAR_H

    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef framework fill:#4CAF50,stroke:#388E3C,color:white
    classDef service fill:#9E9E9E,stroke:#616161,color:white
    classDef health fill:#FFC107,stroke:#FFA000,color:black

    %% Click events for component mapping
    click REG "https://github.com/hynek/svcs/blob/main/src/svcs/_core.py"
    click AIO "https://github.com/hynek/svcs/blob/main/src/svcs/aiohttp.py"
    click FAST "https://github.com/hynek/svcs/blob/main/src/svcs/fastapi.py"
    click FLASK "https://github.com/hynek/svcs/blob/main/src/svcs/flask.py"
    click PYR "https://github.com/hynek/svcs/blob/main/src/svcs/pyramid.py"
    click STAR "https://github.com/hynek/svcs/blob/main/src/svcs/starlette.py"
    click TS "https://github.com/hynek/svcs/blob/main/src/svcs/py.typed"
    click EH "https://github.com/hynek/svcs/blob/main/src/svcs/exceptions.py"
    click AIO_H "https://github.com/hynek/svcs/blob/main/docs/examples/aiohttp/health_check.py"
    click FAST_H "https://github.com/hynek/svcs/blob/main/docs/examples/fastapi/health_check.py"
    click FLASK_H "https://github.com/hynek/svcs/blob/main/docs/examples/flask/health_check.py"
    click PYR_H "https://github.com/hynek/svcs/blob/main/docs/examples/pyramid/health_check.py"
    click STAR_H "https://github.com/hynek/svcs/blob/main/docs/examples/starlette/health_check.py"
```
