# freyam13/asset-grouping-service architecture

> Architecture diagram of the GitHub repository freyam13/asset-grouping-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freyam13/asset-grouping-service
- Repository: https://github.com/freyam13/asset-grouping-service

## Overview

##### Project type and purpose
- This is a backend REST API service (FastAPI) for dynamic grouping of cloud assets based on configurable rules.
- Key purpose: expose endpoints for asset and rule creation/update, evaluate grouping logic in real-time, and return grouped assets.

a. API Layer
- FastAPI app (src/main.py)
- Routes module (src/api/routes.py)
- OpenAPI/Swagger UI (automatic via FastAPI)
b. Service Layer
- GroupingService (src/services/grouping.py)
- Business logic for rule evaluation and group assignment
c. Data Models
- Pydantic schemas (src/models/schemas.py) representing Asset, Tag, GroupingRule, Condition, Operator enum
d. Persistence / Data Store
- In-memory storage or stub repository (future DB integration)
- Placeholder for assets and rules collections
e. Clients / Consumers
- REST clients (e.g., CLI, UI, other services) calling HTTP endpoints
- Tests (pytest suite under tests/)
- Authentication & Authorization service
- Monitoring & Metrics
- Caching layer

##### Relationships and data flow
1. Client HTTP Request → FastAPI Router
2. Router validates request via Pydantic schema → constructs model instance
3. Router calls Service Layer method (e.g., create_asset, create_rule)
4. Service Layer retrieves/stores data in Data Store, evaluates grouping logic:
– Iterate rules
– Match conditions against asset fields
– Assign group_name
5. Service returns domain model → Router serializes to JSON → HTTP Response
6. Swagger UI / OpenAPI generates interactive docs from route metadata

##### Architectural patterns & design principles
- Layered architecture (Adapter/Controller layer vs. Service layer vs. Model layer)
- Separation of concerns: no business logic in route handlers
- Dependency injection (FastAPI’s built-in DI for services)
- Pydantic for validation and type safety
- Clear boundaries for future extension (DB, auth, caching)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        CL["REST Clients/Consumers"]:::external
        Test1["tests/services/test_grouping.py"]:::external
        Test2["tests/conftest.py"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        App["FastAPI App<br/>(entry point)"]:::api
        Routes["Routes Module<br/>(API endpoints)"]:::api
        Swagger["OpenAPI/Swagger UI"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        Service["GroupingService<br/>(business logic)"]:::service
    end

    %% Data Models
    subgraph "Data Models"
        Schemas["Pydantic Schemas<br/>(Asset, Tag, Rule)"]:::models
    end

    %% Data Store
    subgraph "Data Store"
        DataStore["In-Memory Data Store<br/>(assets & rules)"]:::datastore
    end

    %% Documentation
    Doc["README.md"]:::docs

    %% Flow
    CL -->|"HTTP request"| App
    App -->|"include routes"| Routes
    Routes -->|"validate & parse"| Schemas
    Routes -->|"call create_asset/create_rule"| Service
    Service -->|"evaluate rules"| Schemas
    Service -->|"read/write"| DataStore
    Service -->|"return domain model"| Routes
    Routes -->|"serialize JSON"| CL
    Routes -->|"generate docs"| Swagger
    Doc

    %% Click Events
    click App "https://github.com/freyam13/asset-grouping-service/blob/develop/src/main.py"
    click Routes "https://github.com/freyam13/asset-grouping-service/blob/develop/src/api/routes.py"
    click Service "https://github.com/freyam13/asset-grouping-service/blob/develop/src/services/grouping.py"
    click Schemas "https://github.com/freyam13/asset-grouping-service/blob/develop/src/models/schemas.py"
    click DataStore "https://github.com/freyam13/asset-grouping-service/blob/develop/src/services/grouping.py"
    click Test1 "https://github.com/freyam13/asset-grouping-service/blob/develop/tests/services/test_grouping.py"
    click Test2 "https://github.com/freyam13/asset-grouping-service/blob/develop/tests/conftest.py"
    click Doc "https://github.com/freyam13/asset-grouping-service/blob/develop/README.md"

    %% Styles
    classDef external fill:#E8CCFF,stroke:#8666C1,color:#000
    classDef api fill:#BBEFFF,stroke:#007B8A,color:#000
    classDef service fill:#B5FCB5,stroke:#2F8F2F,color:#000
    classDef models fill:#FFD699,stroke:#CC7A00,color:#000
    classDef datastore fill:#CCCCCC,stroke:#666666,color:#000
    classDef docs fill:#F0E6FF,stroke:#A366CC,color:#000
```
