# syeo66/personalary architecture

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

- Interactive diagram: https://gitdiagram.com/syeo66/personalary
- Repository: https://github.com/syeo66/personalary

## Overview

##### Main System Components

a) Frontend Layer (React Application)
- Main React application container
- Component groups:
- Widgets (Clock, Weather, Music Player)
- Admin Interface
- UI Components
- WebSocket Client Connection

b) Backend Layer (Node.js Server)
- API Routes
- Services Layer
- Database Connection
- WebSocket Server
- Configuration Management

c) External Services Integration
- Spotify Remote
- OpenWeatherMap API
- NASA APOD API

##### Component Relationships

a) Client-Server Communication
- WebSocket connection for real-time updates
- REST API calls for admin operations and data fetching
- Bidirectional data flow where applicable

b) Service Integration
- Backend to external API connections
- Database interactions for scenes and screens
- Configuration management flow

##### Specific Implementation Details

- Blue rectangles: Core application components
- Green rectangles: External services
- Yellow diamonds: Data stores
- Purple rectangles: Admin interface components
- Red lines: WebSocket connections
- Black lines: REST API calls
- Orange lines: External API calls

##### Detailed Component Breakdown

Frontend Section:
- Components
- Widgets (Clock, Weather, Music Player)
- Admin Interface
- UI Components
- WebSocket Client

Backend Section:
- API Routes
- Services
- Background Service
- Clock Service
- Weather Service
- Music Player Service
- Messages Service
- Database Layer
- WebSocket Server

##### Key Architectural Patterns to Highlight

- WebSocket-based real-time updates
- Service-based architecture for external integrations
- Component-based frontend architecture
- Configuration-driven behavior

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        App["React App Container"]
        AdminUI["Admin Interface"]
        UIComps["UI Components"]
        WSClient["WebSocket Client"]
        
        subgraph Widgets
            Clock["Clock Widget"]
            Weather["Weather Widget"]
            Music["Music Player Widget"]
        end
        
        App --> Widgets
        App --> AdminUI
        App --> UIComps
        App --> WSClient
    end
    
    subgraph Backend
        WSServer["WebSocket Server"]
        Config["Configuration Management"]
        
        subgraph Services
            BGService["Background Service"]
            ClockService["Clock Service"]
            WeatherService["Weather Service"]
            MusicService["Music Player Service"]
            MsgService["Messages Service"]
        end
        
        subgraph APIRoutes
            AdminRoutes["Admin Routes"]
            SceneRoutes["Scene Routes"]
            ScreenRoutes["Screen Routes"]
        end
        
        DB[(Database)]
    end
    
    subgraph ExternalServices
        Spotify["Spotify API"]
        OpenWeather["OpenWeatherMap API"]
        NASA["NASA APOD API"]
    end
    
    %% Frontend Connections
    WSClient <--> |WebSocket| WSServer
    AdminUI --> |REST| APIRoutes
    
    %% Backend Connections
    APIRoutes --> Services
    Services --> DB
    Services --> WSServer
    Config --> Services
    
    %% External Service Connections
    MusicService --> Spotify
    WeatherService --> OpenWeather
    BGService --> NASA
    
    %% Styling
    classDef frontend fill:#a8d1ff
    classDef backend fill:#b3ffb3
    classDef external fill:#ffcc99
    classDef database fill:#ffff99
    classDef websocket fill:#e6b3ff
    
    class App,AdminUI,UIComps,Clock,Weather,Music frontend
    class WSServer,Config,BGService,ClockService,WeatherService,MusicService,MsgService,AdminRoutes,SceneRoutes,ScreenRoutes backend
    class Spotify,OpenWeather,NASA external
    class DB database
    class WSClient,WSServer websocket
    
    %% Click Events
    click App "https://github.com/syeo66/personalary/blob/main/front/src/App.tsx"
    click AdminUI "https://github.com/syeo66/personalary/blob/main/front/src/pages/Admin/Admin.tsx"
    click UIComps "https://github.com/syeo66/personalary/tree/main/front/src/components/ui/"
    click Clock "https://github.com/syeo66/personalary/tree/main/front/src/components/widgets/Clock/"
    click Weather "https://github.com/syeo66/personalary/tree/main/front/src/components/widgets/Weather/"
    click Music "https://github.com/syeo66/personalary/tree/main/front/src/components/widgets/MusicPlayer/"
    click WSClient "https://github.com/syeo66/personalary/blob/main/front/src/hooks/useWebsocket.ts"
    click BGService "https://github.com/syeo66/personalary/tree/main/server/src/services/background/"
    click ClockService "https://github.com/syeo66/personalary/tree/main/server/src/services/clock/"
    click WeatherService "https://github.com/syeo66/personalary/tree/main/server/src/services/weather/"
    click MusicService "https://github.com/syeo66/personalary/tree/main/server/src/services/musicPlayer/"
    click MsgService "https://github.com/syeo66/personalary/tree/main/server/src/services/messages/"
    click AdminRoutes "https://github.com/syeo66/personalary/blob/main/server/src/routes/adminGet.ts"
    click SceneRoutes "https://github.com/syeo66/personalary/blob/main/server/src/routes/scene.ts"
    click ScreenRoutes "https://github.com/syeo66/personalary/blob/main/server/src/routes/screen.ts"
    click DB "https://github.com/syeo66/personalary/blob/main/server/src/db.ts"
    click Config "https://github.com/syeo66/personalary/blob/main/server/src/ConfigType.ts"
    click Spotify "https://github.com/syeo66/personalary/blob/main/server/src/services/musicPlayer/spotifyRemote.ts"
    click OpenWeather "https://github.com/syeo66/personalary/blob/main/server/src/services/weather/openWeatherMap.ts"
    click NASA "https://github.com/syeo66/personalary/blob/main/server/src/services/background/nasaApotd.ts"
```
