# angeldenom/directes-catala architecture

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

- Interactive diagram: https://gitdiagram.com/angeldenom/directes-catala
- Repository: https://github.com/angeldenom/directes-catala

## Overview

##### Project Type and Purpose
- The project is a full-stack web application with two main parts: an API server and a front-end client.
- Its purpose is to serve as a portal (twitch.cat) that aggregates Twitch streams in Catalan, applies filters based on language and engagement criteria, and provides features like dark mode, public statistics (using Umami), and integration with SafeTwitch.
- The README outlines key functionalities such as filtering based on provided lists, PWA support, and potential integration points for additional content and user subscription features.

##### Analyzing the File Structure
- Notice the top-level directories: "api" and "front".
- The "api" directory contains Go source files (main.go, handlers) and configuration files (Dockerfile, docker-compose.yml, go.mod). It also holds important text files (llista_altres.txt and llista_eliminats.txt) that are used for filtering channels.
- The "front" directory uses Next.js for the UI, with a well-organized structure that includes app pages (e.g., codi-obert, contacte, informa, missió), components, and static assets. Files like next.config.mjs, package.json, and a custom Tailwind config indicate a modern front-end stack.
- Additionally, there are overarching deployment scripts and docker-compose files (deploy.sh, docker-compose.yml) that suggest container orchestration for easy deployment.

##### Examining the README for Architectural Insights
- The README explicitly states that the project is containerized via docker-compose.
- It clearly differentiates the two parts: the API (in Go) and the front-end (in Next.js using shadcn/ui).
- It mentions integration with external systems – for instance, the SafeTwitch instance and analytics via Umami.
- This information, along with the filtering mechanism via text files stored in the API, guides us on how these components interact.

a. Main Components:
- API Container: Built in Go, handling HTTP requests, filtering channels (using llista_altres.txt and llista_eliminats.txt), and serving REST endpoints.
- Front-End Container: Built with Next.js and shadcn/ui, responsible for rendering the user interface and handling client-side logic.
- Data Sources: Text files that drive the filtering logic (llista_altres.txt and llista_eliminats.txt).
- External Services:
- SafeTwitch integration for opening streams on a separate instance.
- Umami for public analytics/statistics.
- Possibly Twitch itself as an external dependency for live streaming data.
- Docker Infrastructure: Containers orchestrated via docker-compose to manage multi-container deployment, along with deployment scripts (deploy.sh).

b. Relationships and Interactions:
- The Front-End communicates with the API over HTTP/REST calls.
- The API accesses internal file-based data (the two lists) for filtering logic.
- Both containers are networked together by docker-compose, ensuring they can communicate.
- External interactions include redirecting or linking to third-party services (SafeTwitch, Umami, and the Twitch platform).

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Clear division between backend (API) and frontend (Next.js) components.
- Containerization: Both main components run within Docker containers for isolation and simplified deployment.
- Extensibility: The API’s usage of filter lists indicates a design prepared for dynamic content management and possible future enhancement (such as user-specific features).

d. Relevant Technologies, Frameworks, and Libraries:
- API: Go language, likely using standard packages for HTTP handling with a Docker environment.
- Front-End: Next.js, React (with TypeScript), Tailwind CSS, and shadcn/ui, which are all clearly integrated in the “front” directory.
- Docker & Docker Compose: For building and orchestrating the separate containers.
- External Services: References to SafeTwitch and Umami.

##### Elements
- Use clear labels for each component:
- “Front-End (Next.js)” for the UI container.
- “API Server (Go)” for the backend container.
- “Docker Compose Orchestration” to denote container management.
- “Filter Data (Text Files)” within the API.
- “External Services” for Twitch, SafeTwitch, and Umami.
- From the Front-End to the API server (to show API calls).
- From the API server to the internal filter data (to indicate data usage for filtering).
- From both main components to External Services (illustrating dependency or integration).
- Data flow directions, especially the requests and responses between UI and API.

- Inside the API container, show a connection to “Filter Data Files” (llista_altres.txt and llista_eliminats.txt).
- External service components (e.g., “Twitch Platform”, “SafeTwitch”, “Umami”) connected with directional lines where applicable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client (Web Browser)"]:::client

    subgraph "Docker Compose Orchestration"
        B["Front-End (Next.js)"]:::frontend
        C["API Server (Go)"]:::backend
    end

    D["API Handlers"]:::backendsub

    subgraph "Filter Data Files"
        F1["llista_altres.txt"]:::data
        F2["llista_eliminats.txt"]:::data
    end

    XP["Twitch Platform"]:::external
    XQ["SafeTwitch"]:::external
    XR["Umami"]:::external

    I["Deployment Scripts"]:::container

    A -->|"HTTP_Request"| B
    B -->|"API_Call"| C
    C -->|"Uses"| D
    C -->|"Reads"| F1
    C -->|"Reads"| F2
    C -->|"Fetches"| XP
    B -->|"LinksTo"| XQ
    B -->|"Analytics"| XR
    I -->|"Manages"| B
    I -->|"Manages"| C

    click B "https://github.com/angeldenom/directes-catala/tree/main/front"
    click C "https://github.com/angeldenom/directes-catala/blob/main/api/main.go"
    click D "https://github.com/angeldenom/directes-catala/tree/main/api/handlers"
    click F1 "https://github.com/angeldenom/directes-catala/blob/main/api/llista_altres.txt"
    click F2 "https://github.com/angeldenom/directes-catala/blob/main/api/llista_eliminats.txt"
    click I "https://github.com/angeldenom/directes-catala/blob/main/docker-compose.yml"

    classDef client fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef frontend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef backend fill:#F5B7B1,stroke:#B03A2E,stroke-width:2px;
    classDef backendsub fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef data fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef external fill:#D6EAF8,stroke:#1F618D,stroke-width:2px;
    classDef container fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
