# kanayaacta/icebreaker architecture

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

- Interactive diagram: https://gitdiagram.com/kanayaacta/icebreaker
- Repository: https://github.com/kanayaacta/icebreaker

## Overview

##### Project type and purpose
- This “IceBreaker” codebase is a backend web service built in Python, using FastAPI (with Uvicorn/Gunicorn) to expose RESTful endpoints for user management, matchmaking, chatting (mcpchat), rating, ranking, results, and categories.
- There is no separate frontend; it is a single-service API layer backed by a relational database (via the `app/database` modules) and calling out to an external OpenAI API for chat or rating-related logic.

##### File structure
- Top-level:
- `main.py` – bootstraps FastAPI
- `app/` – application package
– `routers/` – each file defines a REST router (auth, user, match, category, rating, ranking, mcpchat, graph, result)
– `schemas/` – Pydantic models for request/response payloads
– `database/` – DB connection and CRUD wrapper classes per entity
– `utils/` – helper modules (`openAI.py`, `rating_calculator.py`)
- `requirements.txt`, `pytest` tests under `tests/`, and a standard Python venv setup imply a conventional microservice.

##### Key README insights
- Run with Gunicorn + Uvicorn worker
- Tests invoked via pytest

a. Main components
- Client (could be mobile/app or API tester)
- HTTP Server (Gunicorn + Uvicorn)
- FastAPI Application
– Routers: Auth, User, Match, Category, Rating, Ranking, MCPChat, Graph, Result
– Schemas: Pydantic models
– Utils: OpenAI integration, rating calculator
- Database (e.g., PostgreSQL or MySQL)
- External Service: OpenAI API
- Testing harness (pytest) – can be noted as a side component for CI

b. Relationships & interactions
1. Client → HTTP Server (80/443)
2. HTTP Server → FastAPI app
3. FastAPI dispatches to specific router based on path
4. Router → Schema validation → Handler logic → Database layer (via `connection.py` + entity DB modules)
5. Some handlers call `app/utils/openAI.py` to fetch or process data via OpenAI REST API
6. Business logic may call `rating_calculator.py` for internal computations
7. Responses flow back up to client
8. Tests drive requests through the same HTTP stack or directly call FastAPI endpoints

c. Architectural patterns & design principles
- Layered architecture (API layer, business logic/utils, data access layer)
- Separation of concerns: routers only route + invoke services; database models abstract persistence; utils isolate external API calls & algorithms
- Dependency injection via FastAPI’s builtin features (e.g., passing DB connection into route handlers)
- Pydantic for input/output validation

d. Technologies & frameworks
- Python 3.x, FastAPI, Uvicorn/Gunicorn
- Pydantic (schemas)
- Async or sync DB (likely via SQLAlchemy or raw driver in `connection.py`)
- Pytest for testing
- OpenAI REST API

##### Don’t overthink—be exhaustive
- Break out each router and DB module as its own component
- Explicitly show the schema layer between routers and business logic
- Use of OpenAI and the rating calculator as distinct service calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::client
    Main["main.py"]:::bootstrap
    AppInit["app/__init__.py"]:::app

    subgraph "FastAPI Application"
        subgraph Routers
            AuthR["AuthRouter"]:::api
            UserR["UserRouter"]:::api
            MatchR["MatchRouter"]:::api
            CategoryR["CategoryRouter"]:::api
            RatingR["RatingRouter"]:::api
            RankingR["RankingRouter"]:::api
            MCPChatR["MCPChatRouter"]:::api
            GraphR["GraphRouter"]:::api
            ResultR["ResultRouter"]:::api
        end

        subgraph Schemas
            AuthS["Auth Schemas"]:::schema
            UserS["User Schemas"]:::schema
            MatchS["Match Schemas"]:::schema
            CategoryS["Category Schemas"]:::schema
            RatingS["Rating Schemas"]:::schema
            MCPChatS["MCPChat Schemas"]:::schema
        end

        subgraph "Data Access Layer"
            Conn["DB Connection"]:::db
            UserDB["UserDB"]:::db
            MatchDB["MatchDB"]:::db
            CategoryDB["CategoryDB"]:::db
            RatingDB["RatingDB"]:::db
            MCPChatDB["MCPChatDB"]:::db
        end

        subgraph "Business Logic / Utils"
            OpenAI["OpenAI Client"]:::utils
            RatingCalc["Rating Calculator"]:::utils
        end
    end

    Database[(Database)]:::db
    ExternalOpenAI[(OpenAI API)]:::external

    subgraph "Testing Harness"
        TestsDir["tests/"]:::test
        TestAuth["test_auth_api.py"]:::test
        TestUser["test_user_api.py"]:::test
        TestMatch["test_match_api.py"]:::test
        TestCategory["test_category_api.py"]:::test
        TestRating["test_rating_api.py"]:::test
        TestRanking["test_ranking_api.py"]:::test
        TestResult["test_result_api.py"]:::test
    end

    Client -->|"HTTP request"| Main
    Main -->|"initializes"| AppInit

    AppInit --> AuthR
    AppInit --> UserR
    AppInit --> MatchR
    AppInit --> CategoryR
    AppInit --> RatingR
    AppInit --> RankingR
    AppInit --> MCPChatR
    AppInit --> GraphR
    AppInit --> ResultR

    AuthR --> AuthS
    UserR --> UserS
    MatchR --> MatchS
    CategoryR --> CategoryS
    RatingR --> RatingS
    MCPChatR --> MCPChatS

    AuthR --> Conn
    UserR --> Conn
    MatchR --> Conn
    CategoryR --> Conn
    RatingR --> Conn
    RankingR --> Conn
    MCPChatR --> Conn
    GraphR --> Conn
    ResultR --> Conn

    Conn --> UserDB
    Conn --> MatchDB
    Conn --> CategoryDB
    Conn --> RatingDB
    Conn --> MCPChatDB
    UserDB --> Database
    MatchDB --> Database
    CategoryDB --> Database
    RatingDB --> Database
    MCPChatDB --> Database

    MCPChatR -->|"calls"| OpenAI
    OpenAI --> ExternalOpenAI
    RatingR -->|"uses"| RatingCalc

    TestsDir --> TestAuth
    TestsDir --> TestUser
    TestsDir --> TestMatch
    TestsDir --> TestCategory
    TestsDir --> TestRating
    TestsDir --> TestRanking
    TestsDir --> TestResult

    TestAuth --> Client
    TestUser --> Client
    TestMatch --> Client
    TestCategory --> Client
    TestRating --> Client
    TestRanking --> Client
    TestResult --> Client

    click Main "https://github.com/kanayaacta/icebreaker/blob/main/main.py"
    click AppInit "https://github.com/kanayaacta/icebreaker/blob/main/app/__init__.py"
    click AuthR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/auth.py"
    click UserR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/user.py"
    click MatchR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/match.py"
    click CategoryR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/category.py"
    click RatingR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/rating.py"
    click RankingR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/ranking.py"
    click MCPChatR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/mcpchat.py"
    click GraphR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/graph.py"
    click ResultR "https://github.com/kanayaacta/icebreaker/blob/main/app/routers/result.py"
    click AuthS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/auth.py"
    click UserS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/user.py"
    click MatchS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/match.py"
    click CategoryS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/category.py"
    click RatingS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/rating.py"
    click MCPChatS "https://github.com/kanayaacta/icebreaker/blob/main/app/schemas/mcpchat.py"
    click Conn "https://github.com/kanayaacta/icebreaker/blob/main/app/database/connection.py"
    click UserDB "https://github.com/kanayaacta/icebreaker/blob/main/app/database/user_db.py"
    click MatchDB "https://github.com/kanayaacta/icebreaker/blob/main/app/database/match_db.py"
    click CategoryDB "https://github.com/kanayaacta/icebreaker/blob/main/app/database/category_db.py"
    click RatingDB "https://github.com/kanayaacta/icebreaker/blob/main/app/database/rating_db.py"
    click MCPChatDB "https://github.com/kanayaacta/icebreaker/blob/main/app/database/mcpchat_db.py"
    click OpenAI "https://github.com/kanayaacta/icebreaker/blob/main/app/utils/openAI.py"
    click RatingCalc "https://github.com/kanayaacta/icebreaker/blob/main/app/utils/rating_calculator.py"
    click TestsDir "https://github.com/kanayaacta/icebreaker/tree/main/tests/"
    click TestAuth "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_auth_api.py"
    click TestUser "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_user_api.py"
    click TestMatch "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_match_api.py"
    click TestCategory "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_category_api.py"
    click TestRating "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_rating_api.py"
    click TestRanking "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_ranking_api.py"
    click TestResult "https://github.com/kanayaacta/icebreaker/blob/main/tests/test_result_api.py"

    classDef bootstrap fill:#0D3B66,stroke:#000,color:#fff;
    classDef app fill:#16425B,stroke:#000,color:#fff;
    classDef api fill:#1E7A7A,stroke:#000,color:#fff;
    classDef schema fill:#206A5D,stroke:#000,color:#fff;
    classDef db fill:#2E8B57,stroke:#000,color:#fff;
    classDef utils fill:#FF8C00,stroke:#000,color:#fff;
    classDef external fill:#FFA500,stroke:#000,color:#fff;
    classDef test fill:#A9A9A9,stroke:#000,color:#000;
    classDef client fill:#8B0000,stroke:#000,color:#fff;
```
