THECR3W-DEV — DOKUMENTACJA ARCHITEKTURY SYSTEMU

Wersja: 1.0.0 | Data: 2026-10-31

1. Wprowadzenie i Filozofia Architektury

TheCr3w-dev to zintegrowany, samowystarczalny ekosystem zarządzania cyklem życia oprogramowania, dystrybucją aktualizacji aplikacji natywnych (Android, Windows), magazynowaniem artefaktów binarnych, orkiestracją wdrożeń kontenerowych Docker oraz synchronizacją serwerów zewnętrznych (SFTP/FTPS).

Platforma została zaprojektowana w modelu modularnego monolitu backendowego z rozdzielonymi domenowo interfejsami API oraz niezależnymi aplikacjami frontendowymi:

Separacja domenowa:
- Native Update API (app.thecr3wnet.com): Dystrybucja metadanych wydań, weryfikacja aktualizacji aplikacji Android/Windows, generowanie krótkotrwałych podpisanych adresów URL (Pre-signed S3) do Cloudflare R2, telemetria instalacji i błędów.
- Deployment Control API (app.thecr3wnet.com/control): Rejestracja podpisanych manifestów wdrożeniowych, bramki zatwierdzania produkcji (Production Approval Gateways), zarządzanie immutable digestami Forgejo OCI, komunikacja z Deployment Agentem oraz synchronizacja SFTP/FTPS.
Separacja frontendowa:
- The Cr3w Download Center (download.thecr3wnet.com): Lekki, w 100% publiczny portal prezentacji aplikacji i pobierania wydań. Brak bezpośredniego dostępu do bazy i sekretów R2; komunikacja wyłącznie przez publiczne REST API app.thecr3wnet.com.
- Admin Panel: Chroniony interfejs administracyjny wykorzystujący protokół OIDC (Authorization Code Flow + PKCE) z istniejącym serwerem Keycloak (login.thecr3wnet.com, realm master).
Domena bazowa thecr3wnet.com:
- Czysto infrastrukturalna domena brzegowa. Zgodnie z nadrzędnymi wytycznymi nie posiada i nie będzie posiadać żadnej strony WWW, CMS ani landing page.

2. Diagram Architektury Logicznej i Przepływu Danych

flowchart TD
    subgraph Clients["Warstwa Klientów i Użytkowników"]
        PubUser["Użytkownik Końcowy (Download Center)"]
        AdminUser["Administrator / Release Manager (Admin Panel)"]
        AndroidSDK["Aplikacja Android (TheCr3w Kotlin SDK)"]
        WindowsSDK["Aplikacja Windows (TheCr3w .NET SDK)"]
        ForgejoCI["Forgejo Actions CI/CD"]
    end

    subgraph Ingress["Warstwa Brzegowa (Caddy Reverse Proxy)"]
        CaddyProxy["Caddy v2 (Docker Network: proxy)\nAutomatyczny TLS (Let's Encrypt / ZeroSSL)"]
    end

    subgraph IAM["Zarządzanie Tożsamością (Keycloak)"]
        Keycloak["Keycloak IAM (login.thecr3wnet.com)\nRealm: master | Client Roles"]
    end

    subgraph TheCr3wCore["Rdzeń Ekosystemu TheCr3w-dev (.NET 9 ASP.NET Core)"]
        NativeAPI["Native Update API\n(Updates, Releases, Download URLs)"]
        DeployAPI["Deployment Control API\n(Manifests, Approvals, Rollback)"]
        SharedDomain["TheCr3w.Shared.Domain & Crypto\n(Ed25519 Canonical Signing, SHA256)"]
        
        NativeAPI --- SharedDomain
        DeployAPI --- SharedDomain
    end

    subgraph DataStorage["Warstwa Danych i Magazynu"]
        PostgresDB[("PostgreSQL 16 Alpine\n(Dedykowana baza: thecr3w-postgres)\nWersjonowane migracje DDL")]
        R2Storage["Cloudflare R2 (S3-compatible)\nBucket: thecr3w-app\n(Prywatne binaria APK, EXE, MSI)"]
    end

    subgraph ExecutionPlane["Płaszczyzna Wykonawcza Wdrożeń"]
        DeployAgent["Deployment Agent\n(Izolowany demon z kontrolowaną białą listą operacji)"]
        DockerHost["Docker Engine (Netcup Host)"]
        ExternalSFTP["Zewnętrzne Serwery (SFTP / FTPS)"]
    end

    %% Ingress routing
    PubUser -->|download.thecr3wnet.com| CaddyProxy
    AdminUser -->|Admin UI OIDC| CaddyProxy
    AndroidSDK -->|app.thecr3wnet.com| CaddyProxy
    WindowsSDK -->|app.thecr3wnet.com| CaddyProxy
    ForgejoCI -->|Publikacja wydania / manifestu| CaddyProxy

    CaddyProxy --> NativeAPI
    CaddyProxy --> DeployAPI
    AdminUser -->|Uwierzytelnienie| Keycloak
    DeployAPI -.->|Weryfikacja JWT / JWKS| Keycloak
    NativeAPI -.->|Weryfikacja JWT / JWKS| Keycloak

    NativeAPI --- PostgresDB
    DeployAPI --- PostgresDB

    %% Magazyn R2
    NativeAPI -->|Generowanie Pre-signed GET (15 min)| R2Storage
    NativeAPI -->|Generowanie Pre-signed PUT (Upload)| R2Storage
    PubUser -.->|Bezpośrednie pobieranie artefaktu| R2Storage
    AndroidSDK -.->|Bezpośrednie pobieranie artefaktu| R2Storage
    WindowsSDK -.->|Bezpośrednie pobieranie artefaktu| R2Storage

    %% Płaszczyzna wdrożeniowa
    DeployAPI -->|Podpisany manifest po akceptacji| DeployAgent
    DeployAgent -->|docker pull @sha256 & compose up| DockerHost
    DeployAPI -->|Synchronizacja ze sprawdzonym host-key| ExternalSFTP

3. Model Kryptograficzny (Ed25519)

W celu zapewnienia niezaprzeczalności i integralności wydań oraz manifestów wdrożeniowych stosowany jest algorytm Ed25519 (RFC 8032):

3.1. Podpisywanie Metadanych Wydania (Native Release Metadata)

Podczas publikacji wydania w Native Update API tworzona jest kanoniczna postać JSON metadanych (uporządkowane alfabetycznie klucze, brak zbędnych białych znaków, kodowanie UTF-8):

{"app_id":"com.thecr3w.app","architecture":"arm64-v8a","channel":"stable","file_size":48921024,"mandatory":false,"minimum_supported_version":"1.0.0","platform":"android","published_at":"2026-10-31T12:00:00Z","release_id":"...","sha256":"...","version":"1.2.0","version_code":12}

Metadane są podpisywane prywatnym kluczem Ed25519 przechowywanym wyłącznie w bezpiecznej konfiguracji backendu.
Klienci natywni (Android SDK oraz Windows SDK) posiadają zaszyty lub pobrany przez HTTPS publiczny klucz weryfikujący Ed25519.
Warunek instalacji: Klient natywny weryfikuje podpis Ed25519 metadanych oraz sumę SHA256 pobranego pliku przed zainicjowaniem instalacji.

3.2. Podpisywanie Manifestów Wdrożeniowych (Deployment Manifests)

Każdy manifest generowany w procesie CI/CD (lub przez uprawnionego inżyniera) zawiera immutable_digest obrazu z Forgejo OCI (sha256:...) oraz config_hash.
Manifest jest podpisywany kluczem Ed25519.
Przed wdrożeniem produkcyjnym zatwierdzający (Approver) podpisuje dokładny skrót SHA256 manifestu. Jeśli manifest ulegnie jakiejkolwiek zmianie po zatwierdzeniu, jego SHA256 zmienia się, a wdrożenie zostaje automatycznie zablokowane.

4. Architektura Ról RBAC i Integracja z Keycloak

Instancja Keycloak: https://login.thecr3wnet.com
Realm: master
Klient OIDC Frontend (Admin Panel): thecr3w-admin-panel (Typ: Public, PKCE: S256, Standard Flow)
Klient OIDC Backend (API): thecr3w-backend (Typ: Confidential, Bearer-only / Service Accounts)

Separacja Ról Klienta (Client Roles w realm `master`):

W celu eliminacji ryzyka eskalacji uprawnień w administracyjnym realm master, wszystkie role są definiowane wyłącznie w przestrzeni klienta thecr3w-backend:

Rola Klienta	Uprawnienia
`thecr3w:admin`	Pełne zarządzanie aplikacjami, konfiguracją, kluczami, serwerami zewnętrznymi oraz pełny audyt.
`thecr3w:release-manager`	Tworzenie wydań (Draft), upload artefaktów do R2, podpisywanie i publikowanie wydań, wycofywanie wydań.
`thecr3w:approver`	Zatwierdzanie wdrożeń produkcyjnych (podpisywanie SHA256 manifestów).
`thecr3w:deployer`	Zgłaszanie manifestów wdrożeniowych, uruchamianie wdrożeń na staging/dev, podgląd i synchronizacja SFTP/FTPS.
`thecr3w:viewer`	Dostęp tylko do odczytu: podgląd dashboardu, listy wydań, historii wdrożeń i logów audytowych.

5. Integracja z Magazynem Cloudflare R2

Endpoint API S3: https://bf705752e38169fedb83efd5b747390e.r2.cloudflarestorage.com
Bucket: thecr3w-app
Polityka dostępu: Prywatny bucket (Zero anonimowego listowania).
Struktura kluczy obiektów w R2: apps/{app_id}/{platform}/{channel}/{version}_{version_code}_{arch}_{sha256_short}.{ext}
Przykład: apps/com.thecr3w.app/android/stable/1.2.0_12_arm64-v8a_7a59d813.apk
Proces pobierania:
1. Klient odpytuje GET /api/v1/apps/{app_id}/releases/{release_id}/download.
2. Backend weryfikuje status publikacji wydania i generuje Pre-signed S3 GET URL o ważności 900 sekund (15 minut).
3. Klient pobiera plik binarny bezpośrednio z Cloudflare CDN/R2 z pełną prędkością łącza i weryfikuje SHA256.

8.3 KiB Raw Blame History