# ilmarikyl/semanttuli architecture

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

- Interactive diagram: https://gitdiagram.com/ilmarikyl/semanttuli
- Repository: https://github.com/ilmarikyl/semanttuli

## Overview

##### Main System Components

a) Client-Side (Frontend):
- Sub-components for:
- Game UI Components (src/lib/components)
- State Management (src/stores)
- i18n System (src/lib/i18n)
- Game Logic (src/lib/utils)

b) Server-Side:
- API Routes (src/routes/api)
- Database Service Layer (src/lib/services)

c) External Services:
- MongoDB Database
- Fly.io Deployment Platform (show two instances for EN/FI)

##### Component Relationships

a) Data Flow:
- Client → Server API Endpoints (for word similarities, hints, etc.)
- Server → MongoDB (for word vectors and similarity scores)
- i18n System → UI Components (localization flow)
- Stores → Components (state management flow)

b) API Integration:
- Distinct endpoints:
- /api/getSecret
- /api/hint
- /api/model
- /api/nearby_10
- /api/nearby_1k
- /api/top_similarities

##### Specific Implementation Details

- Language-specific configurations (EN/FI)
- Docker containerization boundary
- Local storage interaction
- Game state management flow

##### Technical Stack Indicators

- SvelteKit
- TypeScript
- Tailwind CSS
- MongoDB
- Docker
- Fly.io

##### Environment Configuration

Configuration flow:
- Environment variables
- Language selection
- Database connection

##### Deployment configuration for both language versions

Keep the abstraction level focused on the architectural components while showing enough detail to understand the game's unique features, particularly the word similarity calculation system and bilingual support.

- Component boundaries
- Environment-specific configurations

This will create a comprehensive yet clear visualization of the system's architecture while highlighting its key features as a bilingual word guessing game.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        UI[Game UI Components]
        State[State Management]
        i18n[i18n System]
        GameLogic[Game Logic]
        
        UI --> State
        UI --> i18n
        UI --> GameLogic
        State --> GameLogic
    end

    subgraph Server
        API[API Routes]
        DBService[Database Service]
        LangConfig[Language Configuration]
        
        API --> DBService
        API --> LangConfig
    end

    subgraph External
        MongoDB[(MongoDB)]
        FlyEN[Fly.io EN Instance]
        FlyFI[Fly.io FI Instance]
    end

    Client --> API
    DBService --> MongoDB
    Server --> FlyEN
    Server --> FlyFI

    subgraph APIEndpoints
        direction TB
        Secret["/api/getSecret"]
        Hint["/api/hint"]
        Model["/api/model"]
        Near10["/api/nearby_10"]
        Near1k["/api/nearby_1k"]
        TopSim["/api/top_similarities"]
    end

    API --> APIEndpoints

    %% Click events for component mapping
    click UI "https://github.com/ilmarikyl/semanttuli/tree/master/src/lib/components/"
    click State "https://github.com/ilmarikyl/semanttuli/tree/master/src/stores/"
    click i18n "https://github.com/ilmarikyl/semanttuli/tree/master/src/lib/i18n/"
    click GameLogic "https://github.com/ilmarikyl/semanttuli/tree/master/src/lib/utils/"
    click API "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/"
    click DBService "https://github.com/ilmarikyl/semanttuli/blob/master/src/lib/services/dbService.ts"
    click LangConfig "https://github.com/ilmarikyl/semanttuli/blob/master/src/lib/config/language.ts"
    click Secret "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/getSecret/"
    click Hint "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/hint/"
    click Model "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/model/"
    click Near10 "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/nearby_10/"
    click Near1k "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/nearby_1k/"
    click TopSim "https://github.com/ilmarikyl/semanttuli/tree/master/src/routes/api/top_similarities/"

    classDef frontend fill:#3b82f6,color:white
    classDef server fill:#22c55e,color:white
    classDef database fill:#eab308,color:white
    classDef external fill:#a855f7,color:white
    classDef api fill:#ef4444,color:white

    class UI,State,i18n,GameLogic frontend
    class API,DBService,LangConfig server
    class MongoDB database
    class FlyEN,FlyFI external
    class Secret,Hint,Model,Near10,Near1k,TopSim api
```
