# bharathganji/pikpak-plus architecture

> Architecture diagram of the GitHub repository bharathganji/pikpak-plus, 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/bharathganji/pikpak-plus
- Repository: https://github.com/bharathganji/pikpak-plus

## Overview

##### Main Components
a. Client Application (pikpak-plus-client)
- Web UI: Built with React, Vite, and IonicFramework.
- Mobile APK: Android project using Capacitor for native integration.
- Components and features: Authentication (sign-up/login), search functionality (using Jackett), file download/rename process, UI elements (forms, spinners, helpers).
b. Backend Application (pikpak-plus-server)
- Flask API: Acts as the gateway for client requests.
- API Modules: Key Python modules (api.py, apiscrape.py, flask_storage.py) handle core business logic.
- PikPak Integration: Communicates with the PikPak API via internal modules.
- Third-Party Integration: Uses Jackett (for torrent search) and Supabase (for user management and database operations).
- Deployment Configurations: Gunicorn configuration for production and Dockerfile for containerized delivery.
c. External Services and Infrastructure
- Supabase: Provides authentication and a MySQL (or similar) database with Row-Level Security policies.
- PikPak: The underlying storage/service account whose features are being shared.
- Jackett: For performing torrent searches and boosting the platform's search functionality.
d. Containerization & Orchestration
- Docker & docker-compose: Orchestrate both the frontend and backend containers, ensuring configuration via provided example.env and docker-compose.yml files.

##### Relationships and Interactions
- The Client Application (whether accessed via a web browser or Android APK) communicates with the Backend through REST API endpoints.
- The Frontend sends user authentication requests, search queries, and file download requests to the Flask backend.
- The Backend authenticates requests using Supabase and serves backend logic – fetching data from PikPak and returning results to the client.
- There is also an external trigger (/ping endpoint) to keep the backend active (via cron-job or similar scheduling service).
- Docker containers encapsulate both frontend and backend, highlighting the separation of concerns and deployment isolation.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly partitioning the UI components (React with Ionic) from the backend logic (Flask).
- Containerization: Use Docker to manage dependencies and deploy the system consistently.
- External Integration: Leverage external API services (Supabase for authentication and Jackett for search) to focus internal development on application-specific logic.
- Modular Design: The project’s file structure reflects a modular design for both UI components (each in separate folders with their own CSS, TSX files) and backend modules.

##### Relevant Technologies
- Frontend: React.js, IonicFramework, Vitejs.
- Backend: Python Flask, Gunicorn.
- DevOps: Docker, docker-compose.
- Additional Tools: Supabase for auth & database, Jackett for torrent search (integrated in the backend).

##### Additional Recommendations
- Detail out each container with its sub-components where necessary (for instance, splitting the client into a UI module and an Android-specific module if relevant).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Devices
    subgraph "User Devices"
        UD1("Web Browser"):::frontend
        UD2("Android Device"):::frontend
    end

    %% Client Application (Frontend)
    subgraph "Client Application (Frontend)"
        FE1("Web UI (React, Vite, Ionic)"):::frontend
        FE2("Mobile APK (Capacitor)"):::frontend
    end

    %% Backend Application
    subgraph "Backend Application"
        BE1("Flask API (Python, Gunicorn)"):::backend
        BE2("PikPak Integration Modules"):::backend
        BE3("Ping Endpoint (/ping)"):::backend
    end

    %% External Services
    subgraph "External Services"
        EX1("Supabase (Auth & DB)"):::external
        EX2("PikPak Service"):::external
        EX3("Jackett (Torrent Search)"):::external
    end

    %% Containerization & Deployment
    subgraph "Containerization & Deployment"
        CT1("Docker Compose"):::infrastructure
        CT2("Client Dockerfile"):::infrastructure
        CT3("Server Dockerfile"):::infrastructure
    end

    %% Flows: Devices to Frontend
    UD1 --> FE1
    UD2 --> FE2

    %% Frontend sends requests to Backend API
    FE1 -->|"REST request"| BE1
    FE2 -->|"REST request"| BE1

    %% Backend internal communications
    BE1 -->|"uses"| BE2
    BE1 -->|"authenticates with"| EX1
    BE1 -->|"integrates with"| EX2
    BE1 -->|"calls"| EX3

    %% Ping endpoint for maintenance
    BE3 --> BE1

    %% Deployment orchestration linking containers to apps
    CT1 --> FE1
    CT1 --> BE1

    %% Click Events for Component Mapping
    click FE1 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-client/src"
    click FE2 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-client/android"
    click BE1 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-server"
    click BE2 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-server/pikpak"
    click CT1 "https://github.com/bharathganji/pikpak-plus/blob/main/docker-compose.yml"
    click CT2 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-client/Dockerfile"
    click CT3 "https://github.com/bharathganji/pikpak-plus/tree/main/pikpak-plus-server/Dockerfile"
    click EX1 "https://github.com/bharathganji/pikpak-plus/blob/main/pikpak-plus-server/supabase_client.py"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef infrastructure fill:#ffdead,stroke:#000,stroke-width:1px;
    
    class UD1,UD2,FE1,FE2 frontend;
    class BE1,BE2,BE3 backend;
    class EX1,EX2,EX3 external;
    class CT1,CT2,CT3 infrastructure;
```
