# pil0u/lewagon-aoc architecture

> Architecture diagram of the GitHub repository pil0u/lewagon-aoc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pil0u/lewagon-aoc
- Repository: https://github.com/pil0u/lewagon-aoc

## Overview

##### Main System Components

a) Client Layer
- Web Interface (Rails Views + ViewComponents)
- JavaScript Controllers (Stimulus)
- TailwindCSS Styling

b) Application Layer
- Controllers (handling HTTP requests)
- Components (ViewComponents architecture)
- Domains (business logic)
- Jobs (background processing)
- Presenters (view logic)

c) Data Layer
- Models (ActiveRecord)
- Database (PostgreSQL)
- Cache System

d) External Services
- Advent of Code API Integration
- OAuth (GitHub)
- Slack Integration

##### Key Architectural Patterns to Highlight

a) MVC Pattern with Enhanced Components
- Traditional Rails MVC
- ViewComponents for reusable UI elements
- Presenters for complex view logic

b) Domain-Driven Design
- Separate domains for different concerns (achievements, completions, ranks, scores)
- Clear business logic separation in domain classes

c) Background Processing
- GoodJob for async operations
- Scheduled tasks for data updates

##### Data Flow Representation

a) Primary Flows
- User authentication flow via GitHub OAuth
- Score computation and caching flow
- Achievement unlocking flow
- API data fetching and processing

b) Secondary Flows
- Real-time updates via Stimulus controllers
- Cache invalidation paths
- Background job processing

##### Component Relationships

Clear connections between:
- Models and their associations
- Controllers and their corresponding views/components
- Domain services and their dependencies
- Background jobs and their triggers

##### Implementation Details

- Ruby/Rails versions (3.3.5/7.2.2.1)
- Database schema highlights
- Key gem dependencies
- Environment configurations

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        UI["Web Interface"]
        JS["JavaScript Controllers"]:::js
        CSS["TailwindCSS"]:::css
    end

    subgraph "Application Layer"
        direction TB
        CTRL["Controllers"]:::controllers
        COMP["ViewComponents"]:::components
        DOM["Domain Logic"]:::domain
        JOBS["Background Jobs"]:::jobs
        PRES["Presenters"]:::presenters
    end

    subgraph "Data Layer"
        direction TB
        MOD["Models"]:::models
        DB[(PostgreSQL)]
        CACHE[("Cache System")]:::cache
    end

    subgraph "External Services"
        direction TB
        AOC["Advent of Code API"]
        OAUTH["GitHub OAuth"]:::oauth
        SLACK["Slack Integration"]:::slack
    end

    subgraph "Domain Services"
        direction TB
        ACH["Achievement System"]:::achievements
        SCORE["Scoring System"]:::scoring
    end

    %% Client Layer Connections
    UI --> CTRL
    UI --> COMP
    JS --> UI
    CSS --> UI

    %% Application Layer Connections
    CTRL --> DOM
    CTRL --> PRES
    CTRL --> COMP
    PRES --> COMP
    DOM --> JOBS
    
    %% Data Layer Connections
    DOM --> MOD
    MOD --> DB
    MOD --> CACHE
    
    %% External Service Connections
    CTRL --> AOC
    CTRL --> OAUTH
    JOBS --> SLACK
    
    %% Domain Service Connections
    DOM --> ACH
    DOM --> SCORE
    JOBS --> ACH
    JOBS --> SCORE

    %% Click Events
    click JS "https://github.com/pil0u/lewagon-aoc/tree/main/app/javascript/controllers"
    click CSS "https://github.com/pil0u/lewagon-aoc/blob/main/config/tailwind.config.js"
    click CTRL "https://github.com/pil0u/lewagon-aoc/tree/main/app/controllers"
    click COMP "https://github.com/pil0u/lewagon-aoc/tree/main/app/components"
    click DOM "https://github.com/pil0u/lewagon-aoc/tree/main/app/domains"
    click JOBS "https://github.com/pil0u/lewagon-aoc/tree/main/app/jobs"
    click PRES "https://github.com/pil0u/lewagon-aoc/tree/main/app/presenters"
    click MOD "https://github.com/pil0u/lewagon-aoc/tree/main/app/models"
    click CACHE "https://github.com/pil0u/lewagon-aoc/tree/main/app/domains/cache"
    click OAUTH "https://github.com/pil0u/lewagon-aoc/blob/main/app/controllers/users/omniauth_callbacks_controller.rb"
    click SLACK "https://github.com/pil0u/lewagon-aoc/blob/main/config/initializers/slack.rb"
    click ACH "https://github.com/pil0u/lewagon-aoc/tree/main/app/domains/achievements"
    click SCORE "https://github.com/pil0u/lewagon-aoc/tree/main/app/domains/scores"

    %% Styling
    classDef js fill:#f7df1e
    classDef css fill:#2965f1
    classDef controllers fill:#87CEEB
    classDef components fill:#DDA0DD
    classDef domain fill:#98FB98
    classDef jobs fill:#FFA500
    classDef presenters fill:#F0E68C
    classDef models fill:#4169E1
    classDef cache fill:#DDA0DD
    classDef oauth fill:#90EE90
    classDef slack fill:#4A154B
    classDef achievements fill:#FFB6C1
    classDef scoring fill:#ADD8E6
```
