# tfikler/lingostroll architecture

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

- Interactive diagram: https://gitdiagram.com/tfikler/lingostroll
- Repository: https://github.com/tfikler/lingostroll

## Overview

##### Main Components

Frontend (Client):
- User Interface Components (show major components like ChatInterface, GoogleStreet, Leaderboard)
- State Management (Context component suggests React Context usage)
- API Integration Layer (represented by the api folder)
- Navigation Components (TopNavBar, LeftNavBar)

Backend (Server):
- Express Routes Layer (showing the four main route groups: db, location, openai, tts)
- Controllers Layer (showing corresponding controllers)
- Service Layer (gameService)
- Libraries/Utilities (db, openai, tts)

External Services:
- OpenAI API
- Google Street View API
- Text-to-Speech Service
- Database (type appears to be configured in db.ts)

##### Component Relationships

- Client-Server Communication:
- Frontend API calls → Backend Routes
- Backend Responses → Frontend Components
- Backend Internal Flow:
- Routes → Controllers → Services → Libraries
- External Service Integration:
- Backend Libraries → External APIs

##### Specific Implementation Details

Frontend Layer:
- Component hierarchy starting from App.js
- Main feature components (AmericanQuestions, ChatInterface, GoogleStreet)
- TypeScript usage (*.tsx files)

Backend Layer:
- Separation of concerns (routes → controllers → services)
- Flow configuration system
- TypeScript implementation

##### Additional Elements

Annotations for:
- Authentication flow (suggested by Login component)
- Game mechanics (implied by gameService)
- Real-time features (chat interface)
- Data persistence flows

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        App["React App"]:::frontend
        UI["UI Components"]:::frontend
        StateManagement["Context Provider"]:::frontend
        APILayer["API Integration"]:::frontend
        
        subgraph UIComponents
            Chat["Chat Interface"]:::frontend
            Street["Google Street View"]:::frontend
            Leader["Leaderboard"]:::frontend
            TopNav["Top Navigation"]:::frontend
            LeftNav["Left Navigation"]:::frontend
        end
        
        App --> UI
        App --> StateManagement
        App --> APILayer
        UI --> UIComponents
    end
    
    subgraph Backend
        Routes["Express Routes"]:::backend
        Controllers["Controllers"]:::backend
        Services["Services"]:::backend
        Libraries["Libraries"]:::backend
        
        subgraph RouteLayer
            DBRoutes["DB Routes"]:::backend
            LocationRoutes["Location Routes"]:::backend
            OpenAIRoutes["OpenAI Routes"]:::backend
            TTSRoutes["TTS Routes"]:::backend
        end
        
        subgraph ControllerLayer
            DBController["DB Controller"]:::backend
            LocationController["Location Controller"]:::backend
            OpenAIController["OpenAI Controller"]:::backend
            TTSController["TTS Controller"]:::backend
        end
        
        subgraph ServiceLayer
            GameService["Game Service"]:::backend
        end
        
        subgraph LibraryLayer
            DBLib["Database Library"]:::backend
            OpenAILib["OpenAI Library"]:::backend
            TTSLib["TTS Library"]:::backend
        end
        
        Routes --> RouteLayer
        RouteLayer --> ControllerLayer
        ControllerLayer --> ServiceLayer
        ServiceLayer --> LibraryLayer
    end
    
    subgraph ExternalServices
        OpenAIAPI["OpenAI API"]:::external
        GoogleAPI["Google Street View API"]:::external
        TTSAPI["Text-to-Speech API"]:::external
        Database["Database"]:::external
    end
    
    APILayer --> Routes
    LibraryLayer --> ExternalServices
    
    %% Click Events
    click App "https://github.com/tfikler/LingoStroll/blob/main/client/src/App.js"
    click Chat "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/ChatInterface/index.tsx"
    click Street "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/GoogleStreet/index.jsx"
    click Leader "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/Leaderboard/index.tsx"
    click TopNav "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/TopNavBar/index.jsx"
    click LeftNav "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/LeftNavBar/index.jsx"
    click StateManagement "https://github.com/tfikler/LingoStroll/blob/main/client/src/components/Context/index.jsx"
    click APILayer "https://github.com/tfikler/LingoStroll/blob/main/client/src/api/db.ts"
    click DBRoutes "https://github.com/tfikler/LingoStroll/blob/main/server/src/routes/dbRoutes.ts"
    click LocationRoutes "https://github.com/tfikler/LingoStroll/blob/main/server/src/routes/locationRoutes.ts"
    click OpenAIRoutes "https://github.com/tfikler/LingoStroll/blob/main/server/src/routes/openaiRoutes.ts"
    click TTSRoutes "https://github.com/tfikler/LingoStroll/blob/main/server/src/routes/ttsRoutes.ts"
    click DBController "https://github.com/tfikler/LingoStroll/blob/main/server/src/controllers/dbController.ts"
    click LocationController "https://github.com/tfikler/LingoStroll/blob/main/server/src/controllers/locationController.ts"
    click OpenAIController "https://github.com/tfikler/LingoStroll/blob/main/server/src/controllers/openaiController.ts"
    click TTSController "https://github.com/tfikler/LingoStroll/blob/main/server/src/controllers/ttsController.ts"
    click GameService "https://github.com/tfikler/LingoStroll/blob/main/server/src/service/gameService.ts"
    click DBLib "https://github.com/tfikler/LingoStroll/blob/main/server/src/libs/db.ts"
    click OpenAILib "https://github.com/tfikler/LingoStroll/blob/main/server/src/libs/openai.ts"
    click TTSLib "https://github.com/tfikler/LingoStroll/blob/main/server/src/libs/tts.ts"
    
    %% Styling
    classDef frontend fill:#2196F3,stroke:#1565C0,color:white
    classDef backend fill:#4CAF50,stroke:#2E7D32,color:white
    classDef external fill:#9C27B0,stroke:#6A1B9A,color:white
    
    %% Legend
    subgraph Legend
        Frontend_L["Frontend Component"]:::frontend
        Backend_L["Backend Component"]:::backend
        External_L["External Service"]:::external
    end
```
