# luxkatana/goback architecture

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

- Interactive diagram: https://gitdiagram.com/luxkatana/goback
- Repository: https://github.com/luxkatana/goback

## Overview

##### Project type and purpose
- goback is a full-stack web application (“a pocket-sized version of wayback”) that lets users capture, store, and browse archived snapshots of web pages.
- The backend is written in Python (webserver.py using a minimal web framework), and the frontend is a React + TypeScript single-page application built with Vite.
- It relies on external services: an Appwrite storage bucket for binary/html storage, and a MySQL database for metadata.

##### File structure
Top-level (backend)
- webserver.py – HTTP API endpoints for user auth, job management, snapshot retrieval
- scraper.py – fetches and processes target web pages, saves artifacts
- models.py – ORM definitions mapping jobs, snapshots, users to MySQL
- appwrite_session.py – wrapper to authenticate & talk to Appwrite storage
- config_manager.py – loads .env, goback.toml settings
- Dockerfile & compose.yaml – container definitions for backend, MySQL; orchestrates services
- test_html_documents/ – sample documents for scraper unit tests
- requirements.txt – Python dependencies

goback-frontend (frontend)
- src/routes – page-level React components (Login, Dashboard, CreateBackupPage, JobViewer, etc.)
- src/components & src/components/ui – UI building blocks (Navbar, ProtectedComponent, theming, toasters)
- src/utils/AuthContext.tsx – React context for auth state
- tsconfig*, package.json, vite.config.ts – TS/vite build config

##### README for insights
- States prerequisites: Python3, Appwrite API key + bucket, MySQL server, Docker Compose
- Installation uses Docker Compose to wire up the backend and MySQL; Appwrite is assumed as a managed/external service

##### Main components & interactions
a. Components
– Client (Browser) running React SPA
– goback-frontend container (serving the built SPA or dev server)
– Backend API container (Python webserver + scraper)
– MySQL database container (metadata store)
– Appwrite service (external storage bucket)

b. Data flows & relationships
1. User → Browser → goback-frontend UI
2. Frontend sends HTTPS requests to Backend API (login, signup, list jobs, create job)
3. Backend API reads/writes metadata in MySQL (users, jobs, snapshot records)
4. When a user triggers “Create Backup,” Backend invokes scraper.py
- scraper fetches the target URL, downloads assets (HTML, JS, CSS, media)
- scraper pushes each artifact to Appwrite via appwrite_session API
- scraper updates the job’s status & records in MySQL
5. For “View Job,” Frontend asks Backend for snapshot metadata & presigned URLs → Backend queries MySQL & generates Appwrite URLs → Frontend displays archived content

c. Architectural patterns & design principles
– Separation of concerns: frontend SPA vs. backend API vs. data stores
– Single-page app with protected routes (ProtectedComponent wrapper)
– Background task pattern: synchronous or queued scraping sub-process within the backend
– Configuration driven by environment (.env) + goback.toml + config_manager
– Containerized micro-services (via Docker Compose) on an isolated network

d. Key technologies & frameworks
– React + TypeScript + Vite for the UI
– Python 3 + minimal web framework (Flask/FastAPI) for the API
– SQLAlchemy or equivalent ORM (models.py) for MySQL
– Appwrite REST SDK (appwrite_session.py) for object storage
– Docker & Docker Compose for local/production orchestration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Client
    User((User)):::external
    Browser["Browser"]:::external
    User -->|uses| Browser
    Browser -->|loads SPA| FrontendContainer

    %% Frontend Layer
    subgraph "goback-frontend (React SPA)" 
        direction TB
        FrontendContainer["React SPA<br/>(Vite, TypeScript)"]:::ui
        Routes["src/routes"]:::ui
        UIComponents["src/components & src/components/ui"]:::ui
        AuthContext["src/utils/AuthContext.tsx"]:::ui
        ConfigFiles["package.json<br/>vite.config.ts<br/>tsconfig*.json"]:::ui
    end

    %% Backend Layer
    subgraph "Docker Compose Network" 
        direction TB
        ApiContainer["Python API<br/>(FastAPI/Flask)"]:::api
        ScraperProc["Scraper subprocess"]:::api
        ModelsCode["models.py (ORM)"]:::api
        ConfigMgr["config_manager.py"]:::api
        Requirements["requirements.txt"]:::api
        Tests["test_html_documents/"]:::api
        ApiContainer -->|invokes| ScraperProc
        ApiContainer -->|uses| ModelsCode
        ApiContainer -->|loads| ConfigMgr
        ApiContainer -->|deps| Requirements
        ScraperProc -->|unit tests| Tests
    end

    %% Data Stores and External
    subgraph "Data & Storage"
        direction TB
        MySQLDB[(MySQL Database<br/>metadata store)]:::db
        AppwriteSvc["Appwrite Storage Bucket"]:::ext
    end

    %% Orchestration Layer
    subgraph "Orchestration" 
        direction TB
        ComposeFile["compose.yaml"]:::infr
        Dockerfile["Dockerfile"]:::infr
    end

    %% Data Flows
    FrontendContainer -->|HTTPS requests| ApiContainer
    ApiContainer -->|reads/writes metadata| MySQLDB
    ScraperProc -->|stores artifacts| AppwriteSvc
    ApiContainer -->|generates presigned URLs| AppwriteSvc
    AppwriteSvc -->|serves artifacts| FrontendContainer

    %% Click Events for Component Mapping
    click FrontendContainer "https://github.com/luxkatana/goback/tree/main/goback-frontend/"
    click Routes "https://github.com/luxkatana/goback/tree/main/goback-frontend/src/routes/"
    click UIComponents "https://github.com/luxkatana/goback/tree/main/goback-frontend/src/components/"
    click AuthContext "https://github.com/luxkatana/goback/blob/main/goback-frontend/src/utils/AuthContext.tsx"
    click ConfigFiles "https://github.com/luxkatana/goback/blob/main/goback-frontend/package.json"
    click ConfigFiles "https://github.com/luxkatana/goback/blob/main/goback-frontend/vite.config.ts"
    click ConfigFiles "https://github.com/luxkatana/goback/blob/main/goback-frontend/tsconfig.json"
    click ApiContainer "https://github.com/luxkatana/goback/blob/main/webserver.py"
    click ScraperProc "https://github.com/luxkatana/goback/blob/main/scraper.py"
    click ModelsCode "https://github.com/luxkatana/goback/blob/main/models.py"
    click ConfigMgr "https://github.com/luxkatana/goback/blob/main/config_manager.py"
    click Requirements "https://github.com/luxkatana/goback/blob/main/requirements.txt"
    click Tests "https://github.com/luxkatana/goback/tree/main/test_html_documents/"
    click ComposeFile "https://github.com/luxkatana/goback/blob/main/compose.yaml"
    click Dockerfile "https://github.com/luxkatana/goback/tree/main/Dockerfile"

    %% Styles
    classDef ui fill:#b3ffb3,stroke:#333,stroke-width:1px
    classDef api fill:#fff2b3,stroke:#333,stroke-width:1px
    classDef db fill:#b3e0ff,stroke:#333,stroke-width:1px
    classDef ext fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef infr fill:#e6e6e6,stroke:#333,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#999,stroke-dasharray: 2 2,stroke-width:1px
```
