# bucanero/pkgi-ps3 architecture

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

- Interactive diagram: https://gitdiagram.com/bucanero/pkgi-ps3
- Repository: https://github.com/bucanero/pkgi-ps3

## Overview

##### Project Type and Purpose
- Project Type: Native console (PS3) homebrew application written in C, using PSL1GHT SDK.
- Purpose: Presents a UI to browse a text-based database of `.pkg` payloads, supports filtering/searching, downloads via direct HTTP or PS3’s native Download Manager, generates `.rif` activation files, and manages local files.

##### File Structure
- `source/` + `include/`: Core C modules and headers, implementing subsystems—menu, dialog, config, DB parser, downloader, SHA256, TTF renderer, PS3-specific code, rif generation, audio via MikMod.
- `data/` + `pkgfiles/`: Static assets (images, fonts, sample USRDIR layout) shipped with the app.
- `docs/`: Build/deploy scripts, site config.
- Top-level: `Makefile`, build config, CI workflows, licensing, README, CHANGELOG.

##### README for Architecture & Dependencies
- Layers described: UI, database format parser, download manager (direct vs. background), content activation, update checker.
- External dependencies: PSL1GHT, Tiny3D + YA2D (rendering), PolarSSL (crypto), libcurl (HTTP), MikMod (audio), Mini18n (i18n), dbglogger (logging).

1. UI Layer
– Tiny3D + YA2D + ttf_render
– Menu Controller, Dialog Controller
2. Core Logic
– pkgi.c (app entry, event loop)
– Config Manager (pkgi_config)
– DB Parser / Manager (pkgi_db, custom dbformat)
– Download Manager (pkgi_download)
– Activation Engine (rifrap + ecdsa)
– Update Checker (online sync)
3. Libraries & Helpers
– libcurl (HTTP client for direct mode)
– PSL1GHT SDK (PS3 syscalls: File I/O, threads, DM API)
– PolarSSL (SHA256, ECDSA)
– MikMod Loader
– Mini18n (localization)
– dbglogger (UDP debug logging)
4. File System & Runtime Environment
– `/dev_hdd0/game/NP00PKGI3/USRDIR/` (pkgi.txt, config.txt, dbformat.txt)
– `/dev_hdd0/exdata/` (generated .rap files)
– `/dev_hdd0/tmp/pkgi/` (in-progress `.pkg`)
5. External Services
– Remote CSV/TSV URL endpoints for online DB
– HTTP servers hosting `.pkg` files

– UI Layer → Core Logic (user inputs → commands)
– Core Logic → DB Manager (load/parse local or remote DB)
– Core Logic → Download Manager → External HTTP Servers or PS3 Download Manager
– Download Manager → File System (write `.pkg` to tmp)
– Activation Engine → PSL1GHT Crypto API → File System (`.rap` in exdata)
– Update Checker → External Services → DB Manager (refresh local DB)
– Core Logic → Logging (dbglogger → UDP multicast)
– Core Logic → Audio (MikMod → sound output)

c. Architectural Patterns & Principles
– Layered architecture (UI / application logic / services / OS)
– Separation of concerns: UI vs. data vs. networking vs. activation
– Pluggable DB format (strategy pattern for delimiters/columns)
– Dual-mode download (direct HTTP vs. background DM)

d. Key Technologies / Frameworks
– PSL1GHT (PS3 native APIs)
– Tiny3D + YA2D (2D rendering engine)
– libcurl (network)
– PolarSSL (crypto)
– MikMod (audio)
– Mini18n (i18n)

##### Capturing Essential Details
- Custom DB format loader as a configurable strategy object.
- Build-time dependencies (Makefile → PSL1GHT, YA2D, PolarSSL, libcurl, MikMod, mini18n, dbglogger).
- Optionally, illustrate the CI workflow (.github/workflows/build.yml) as a side note.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        Tiny3DYA2D["Tiny3D + YA2D"]:::ui
        TTF_Render["TTF Rendering"]:::ui
        MenuCtrl["Menu Controller"]:::ui
        DialogCtrl["Dialog Controller"]:::ui
    end

    %% Core Logic
    subgraph "Core Logic" 
        direction TB
        AppEntry["pkgi.c (Entry & Main Loop)"]:::core
        PS3Integrations["pkgi_ps3.c (PS3 Integrations)"]:::core
        ConfigMgr["pkgi_config"]:::core
        DBParser["pkgi_db (DB Parser/Manager)"]:::core
        DownloadMgr["pkgi_download (Download Manager)"]:::core
        SHA256["pkgi_sha256 (SHA256 Utility)"]:::core
        Activation["RIF Activation Engine"]:::core
        UpdateChk["Update Checker"]:::core
    end

    %% Libraries & Helpers
    subgraph "Libraries & Helpers"
        direction TB
        PSL1GHT["PSL1GHT SDK"]:::lib
        Libcurl["libcurl (HTTP Client)"]:::lib
        PolarSSL["PolarSSL (Crypto)"]:::lib
        MikMod["MikMod Loader"]:::lib
        Mini18n["Mini18n (i18n)"]:::lib
        Dbglogger["dbglogger (UDP Logging)"]:::lib
        StyleUtils["Style & Utils"]:::lib
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DBEndpoints["Remote CSV/TSV Endpoints"]:::external
        HTTPServers["HTTP Servers (.pkg hosting)"]:::external
    end

    %% File System & Runtime
    subgraph "PS3 File System" 
        direction TB
        USRDIR["[( /dev_hdd0/game/NP00PKGI3/USRDIR/ )]"]:::fs
        EXDATA["[( /dev_hdd0/exdata/ )]"]:::fs
        TMP["[( /dev_hdd0/tmp/pkgi/ )]"]:::fs
    end

    %% Connections UI -> Core
    Tiny3DYA2D -->|renders UI| AppEntry
    TTF_Render -->|renders fonts| AppEntry
    MenuCtrl -->|user commands| AppEntry
    DialogCtrl -->|dialogs| AppEntry

    %% Core Interactions
    AppEntry -->|calls| ConfigMgr
    AppEntry -->|loads| DBParser
    AppEntry -->|triggers| DownloadMgr
    AppEntry -->|verifies| SHA256
    AppEntry -->|activates| Activation
    AppEntry -->|checks updates| UpdateChk
    AppEntry -->|integrates| PS3Integrations

    %% Download flows
    DownloadMgr -->|HTTP GET| Libcurl
    DownloadMgr -->|PS3 DM API| PS3Integrations
    DownloadMgr -->|writes .pkg| TMP
    UpdateChk -->|HTTP GET| DBEndpoints
    UpdateChk -->|refresh| DBParser

    %% Activation flow
    Activation -->|ECDSA sign| PolarSSL
    Activation -->|writes .rap| EXDATA

    %% DB parsing flows
    DBParser -->|reads| USRDIR
    DBParser -->|parses| DBEndpoints

    %% Config & Logging & Audio
    ConfigMgr -->|reads| USRDIR
    AppEntry -->|logs| Dbglogger
    AppEntry -->|plays audio| MikMod

    %% PSL1GHT OS interactions
    PS3Integrations -->|file I/O| USRDIR
    PS3Integrations -->|threads & DM| PSL1GHT

    %% External hosting
    HTTPServers -->|hosts| DBEndpoints

    %% Libraries usage
    AppEntry -->|crypto| PolarSSL
    AppEntry -->|i18n| Mini18n

    %% Build & CI (side)
    Makefile["Makefile"]:::build
    CI[".github/workflows/build.yml"]:::build

    Makefile -->|build deps| PSL1GHT
    Makefile -->|build deps| Tiny3DYA2D
    Makefile -->|build deps| PolarSSL
    Makefile -->|build deps| Libcurl
    Makefile -->|build deps| MikMod
    Makefile -->|build deps| Mini18n
    Makefile -->|build deps| Dbglogger
    CI -->|runs build| Makefile

    %% Click Events
    click TTF_Render "https://github.com/bucanero/pkgi-ps3/blob/master/include/ttf_render.h"
    click MenuCtrl "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_menu.h"
    click DialogCtrl "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_dialog.h"
    click AppEntry "https://github.com/bucanero/pkgi-ps3/blob/master/source/pkgi.c"
    click PS3Integrations "https://github.com/bucanero/pkgi-ps3/blob/master/source/pkgi_ps3.c"
    click ConfigMgr "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_config.h"
    click DBParser "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_db.h"
    click DownloadMgr "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_download.h"
    click SHA256 "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_sha256.h"
    click Activation "https://github.com/bucanero/pkgi-ps3/blob/master/source/rifrap.c"
    click MikMod "https://github.com/bucanero/pkgi-ps3/blob/master/include/mikmod_loader.h"
    click StyleUtils "https://github.com/bucanero/pkgi-ps3/blob/master/include/pkgi_style.h"
    click USRDIR "https://github.com/bucanero/pkgi-ps3/tree/master/pkgfiles/USRDIR/"
    click TMP "https://github.com/bucanero/pkgi-ps3/tree/master/pkgfiles/USRDIR/"
    click EXDATA "https://github.com/bucanero/pkgi-ps3/tree/master/pkgfiles/USRDIR/"
    click Makefile "https://github.com/bucanero/pkgi-ps3/tree/master/Makefile"
    click CI "https://github.com/bucanero/pkgi-ps3/blob/master/.github/workflows/build.yml"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#2980B9,color:#1B2631
    classDef core fill:#ABEBC6,stroke:#27AE60,color:#1B2631
    classDef lib fill:#D2B4DE,stroke:#8E44AD,color:#1B2631
    classDef external fill:#F9E79F,stroke:#F1C40F,color:#1B2631
    classDef fs fill:#F5CBA7,stroke:#D35400,color:#1B2631
    classDef build fill:#D5DBDB,stroke:#7B7D7D,color:#1B2631
```
