# tellytv/go.xtream-codes architecture

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

- Interactive diagram: https://gitdiagram.com/tellytv/go.xtream-codes
- Repository: https://github.com/tellytv/go.xtream-codes

## Overview

##### Project Type and Purpose
- This is a Go client library (SDK) for interacting with Xtream-Codes IPTV servers. It provides a set of high-level functions to authenticate, fetch live/VOD categories and streams, and optionally invoke ffmpeg for stream processing.

##### File Structure Analysis
- Top-level Go modules:
- xtream-codes.go – core client interface & request orchestration
- structs.go / flex_types.go – domain models and flexible JSON type handling
- base64.go – utility for encoding/decoding (used in authentication)
- ffmpeg.go – wrapper around ffmpeg CLI for stream conversion or probing
- Testing:
- xtream-codes_test.go – unit tests for client functions
- testData/… – JSON fixtures for multiple providers (eternal, hellraiser, iris, tnt)
- Tooling/config:
- .circleci/config.yml – CI pipeline setup
- .gometalinter.json – linting rules

##### Insights from README
- Confirms the library’s sole role is to provide an API to Xtream-Codes servers.
- Minimal external dependencies: Go stdlib, ffmpeg (optional), no UI/DB.

a. Main Components
1. Client Application (your downstream service or microservice)
2. go.xtream-codes Library
– HTTP Client Module
– Authentication Module (base64 utility)
– Models / JSON Parser (structs.go + flex_types.go)
– ffmpeg Integration (ffmpeg.go)
3. External Services
– Xtream-Codes HTTP API Servers
– ffmpeg CLI binary
4. Dev/CI Environment
– Test Runner (uses testData fixtures)
– CircleCI pipeline

b. Relationships & Data Flows
1. The Client App imports go.xtream-codes and calls Authenticate().
2. Library’s Auth Module encodes credentials (base64.go) → HTTP Client issues POST to Xtream API.
3. HTTP Client receives JSON → Models/JSON Parser maps to Go structs.
4. Client App calls GetLiveStreams(), GetSeries(), etc.
5. Library may invoke ffmpeg CLI (ffmpeg.go) for stream manipulation.
6. CI Pipeline checks code quality → runs unit tests against testData fixtures.

c. Architectural Patterns & Principles
- Modular separation:
- Utilities (base64, flex types)
- Core client logic (xtream-codes.go)
- Integration points (ffmpeg wrapper)
- Single responsibility: each .go file/module has a distinct concern.
- Test-driven data validation: fixtures under testData drive struct accuracy.

d. Key Technologies & Frameworks
- Language: Go (modules via go.mod)
- HTTP/JSON: net/http, encoding/json
- External: ffmpeg CLI
- CI/Linters: CircleCI, gometalinter

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application Layer
    subgraph "Client Application"
        direction TB
        ClientApp["Downstream Client App"]:::app
    end

    %% Library Layer
    subgraph "go.xtream-codes Library"
        direction TB
        HTTPClient["HTTP Client Module\n(xtream-codes.go)"]:::library
        Auth["Authentication Module\n(base64.go)"]:::library
        Structs["Domain Models\n(structs.go)"]:::library
        FlexTypes["Flexible JSON Types\n(flex_types.go)"]:::library
        Ffmpeg["ffmpeg Integration\n(ffmpeg.go)"]:::library
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        XtreamAPI["Xtream-Codes HTTP API Server"]:::external
        FfmpegCLI["ffmpeg CLI Binary"]:::external
    end

    %% Development & QA Layer
    subgraph "Development / QA"
        direction TB
        CI["CircleCI Pipeline\n(.circleci/config.yml)"]:::ci
        Tests["Unit Tests\n(xtream-codes_test.go)"]:::ci
        Fixtures["Test Fixtures\ntestData/"]:::ci
    end

    %% Project Config & Documentation
    subgraph "Project Config & Docs"
        direction TB
        GoMod["go.mod"]:::ci
        GoSum["go.sum"]:::ci
        Readme["README.md"]:::ci
        License["LICENSE"]:::ci
        Linter[".gometalinter.json"]:::ci
    end

    %% Data Flows & Relationships
    ClientApp -->|"imports & calls Authenticate()"| Auth
    Auth -->|"encodes credentials"| Auth
    Auth -->|"delegates request"| HTTPClient
    HTTPClient -->|"POST /authenticate"| XtreamAPI
    XtreamAPI -->|"JSON response"| HTTPClient
    HTTPClient -->|"maps JSON"| Structs
    HTTPClient -->|"maps JSON"| FlexTypes
    ClientApp -->|"calls GetStreams()/GetSeries()"| HTTPClient
    HTTPClient -->|"invokes stream helper"| Ffmpeg
    Ffmpeg -->|"executes CLI"| FfmpegCLI

    %% CI/Test flows
    CI -->|"runs tests"| Tests
    Tests -->|"use fixtures"| Fixtures
    CI -->|"runs lint rules"| Linter
    Tests --> HTTPClient
    Tests --> Auth
    Tests --> Structs
    Tests --> FlexTypes
    Tests --> Ffmpeg

    %% Click Events
    click HTTPClient "https://github.com/tellytv/go.xtream-codes/blob/master/xtream-codes.go"
    click Auth "https://github.com/tellytv/go.xtream-codes/blob/master/base64.go"
    click Structs "https://github.com/tellytv/go.xtream-codes/blob/master/structs.go"
    click FlexTypes "https://github.com/tellytv/go.xtream-codes/blob/master/flex_types.go"
    click Ffmpeg "https://github.com/tellytv/go.xtream-codes/blob/master/ffmpeg.go"
    click Tests "https://github.com/tellytv/go.xtream-codes/blob/master/xtream-codes_test.go"
    click Fixtures "https://github.com/tellytv/go.xtream-codes/tree/master/testData/"
    click CI "https://github.com/tellytv/go.xtream-codes/blob/master/.circleci/config.yml"
    click GoMod "https://github.com/tellytv/go.xtream-codes/blob/master/go.mod"
    click GoSum "https://github.com/tellytv/go.xtream-codes/blob/master/go.sum"
    click Readme "https://github.com/tellytv/go.xtream-codes/blob/master/README.md"
    click License "https://github.com/tellytv/go.xtream-codes/tree/master/LICENSE"
    click Linter "https://github.com/tellytv/go.xtream-codes/blob/master/.gometalinter.json"

    %% Styles
    classDef app fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef library fill:#D0F0D0,stroke:#000,stroke-width:1px
    classDef external fill:#FFE4B3,stroke:#000,stroke-width:1px
    classDef ci fill:#E0E0E0,stroke:#000,stroke-width:1px
```
