# poulcuzz/ksef-import architecture

> Architecture diagram of the GitHub repository poulcuzz/ksef-import, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poulcuzz/ksef-import
- Repository: https://github.com/poulcuzz/ksef-import

## Overview

##### Typ projektu i cel (z plików + README)
To **lekka aplikacja webowa (single-page UI + PHP backend)** służąca do **importowania (w praktyce eksportu z KSeF i pobrania) faktur z Krajowego Systemu e‑Faktur** w kilku krokach.

- **Frontend:** statyczne `index.html + styles.css + app.js` (formularz, wywołania API, pobranie ZIP do przeglądarki).
- **Backend:** `api.php` jako pojedynczy entrypoint (router po parametrze `action=`), logika w `src/**`.
- **Integracja zewnętrzna:** komunikacja z **KSeF API** (różne środowiska demo/test/prod).
- **Bezpieczeństwo:** autoryzacja tokenem lub certyfikatem, szyfrowanie **RSA-OAEP + AES-256**, obsługa kluczy i decrypt pliku ZIP.
- **Stan/artefakty lokalne:** logi w `logs/`, pliki tymczasowe w `temp/`, cache kluczy w `src/**/keys_cache`.

Wniosek do diagramu: to nie jest mikroserwis ani rozbudowany system; to **monolit PHP + statyczny front** z wyraźnymi modułami: API Actions, Auth, Export, HTTP client, Logger.

##### Jak czytać strukturę i jak ją przełożyć na architekturę (mapowanie katalogów → komponenty)
Najważniejsze elementy do narysowania wynikają bezpośrednio z folderów w `src`:

##### Warstwa API (routing + actions)
- `api.php` – **HTTP entrypoint**; wybiera akcję na podstawie `action=...` i metody (GET/POST).
- `src/Api/Actions/*Action.php` – **kontrolery/handlery** dla endpointów:
- `StartExportAction.php` (w README endpoint start_import; nazewnictwo w kodzie sugeruje eksport KSeF)
- `StartImportWithCertificateAction.php`
- `CheckStatusAction.php`
- `DownloadAction.php`
- `src/Api/ErrorHandler.php` – centralna obsługa błędów i czytelne komunikaty.
- `src/Api/Helpers.php` – utilsy (walidacje/formatowanie/odpowiedzi).

**Na diagramie:** pokaż `api.php` jako “API Gateway/Router” → strzałki do “Actions”.

##### Warstwa orchestration / service
- `src/KsefService.php` – prawdopodobnie **główny serwis** spinający: auth → wywołanie KSeF → przygotowanie pobrania → logowanie.

**Na diagramie:** “KsefService (Application Service)” jako centralny komponent, do którego wołają Actions.

##### Auth (strategie autoryzacji + szyfrowanie tokena)
- `src/Auth/AuthenticatorInterface.php` – kontrakt strategii.
- `src/Auth/KsefAuthenticator.php` – autoryzacja tokenem.
- `src/Auth/CertificateAuthenticator.php` – autoryzacja certyfikatem/XAdES.
- `src/Auth/TokenEncryptor.php` – szyfrowanie (RSA-OAEP + AES-256).
- Cache kluczy (w README): `src/Auth/keys_cache/*` (np. `token_key_demo.pem`).

**Na diagramie:** “Auth Module” z dwoma wariantami (Token vs Certificate) + komponent “TokenEncryptor/KeyCache”.

##### Export / Download (obsługa szyfrowania plików i ZIP)
- `src/Export/KsefExporter.php` – logika eksportu z KSeF (inicjacja, status, pobranie).
- `src/Export/EncryptionHandler.php` – metadane szyfrowania/klucze sesyjne.
- `src/Export/FileDecryptor.php` – deszyfracja pobranego pliku.
- `src/Export/ExporterInterface.php` – kontrakt.
- Cache kluczy (w README): `src/Export/keys_cache/public_key_*.pem`
- `last_export_encryption.json` (w README) – **stan szyfrowania** ostatniego eksportu (ważne dla “download”).

**Na diagramie:** “Export Module” + “Local encryption metadata store (last_export_encryption.json)”.

##### HTTP client (integracja z KSeF)
- `src/Http/KsefClient.php` – klient HTTP (curl) do KSeF API.

**Na diagramie:** “KsefClient” → strzałka do zewnętrznego “KSeF API (demo/test/prod)”.

##### Logowanie i pliki
- `src/Logger/JsonLogger.php`, `LoggerInterface.php` – logowanie operacji API do plików.
- `logs/` – persystencja logów.
- `temp/` – pliki tymczasowe (i `.htaccess` sugeruje ochronę przed bezpośrednim listingiem/pobraniem).

**Na diagramie:** “File System Storage” z podziałem na `logs/` i `temp/`.

##### Browser (UI)
2. **Static Web Assets**: `index.html`, `app.js`, `styles.css` (serwowane przez PHP built-in albo Apache/Nginx)
##### PHP Backend
- `api.php` router
- `Actions`
- `KsefService`
- moduły: `Auth`, `Export`, `Http`, `Logger`
##### Local File Storage
- `temp/` (ZIP i/lub zaszyfrowane pliki)
- `logs/` (JSON logi)
- `keys_cache/` i `last_export_encryption.json` (stan/klucze)

##### Relacje / przepływy (strzałki z opisem)
Narysuj przynajmniej 4 główne przepływy odpowiadające endpointom:

##### Start import (token)
Browser → `POST api.php?action=start_import` → `StartExportAction/StartImportAction` → `KsefService`
→ `KsefAuthenticator` + `TokenEncryptor` (RSA/AES, klucze)
→ `KsefClient` → **KSeF API**
→ zapis: `last_export_encryption.json` / pliki w `temp/` (jeśli już pobiera)
→ `JsonLogger` → `logs/`

##### Start import (certificate)
Browser → `POST api.php?action=start_import_certificate` → `StartImportWithCertificateAction`
→ `CertificateAuthenticator` → `KsefClient` → **KSeF API** → logi/stan jak wyżej

##### Check status
Browser → `GET api.php?action=check_status` → `CheckStatusAction`
→ `KsefService` → `KsefClient` → **KSeF API** → status → Browser
(+ logowanie)

##### Download ZIP
Browser → `GET api.php?action=download` → `DownloadAction`
→ `KsefService` / `KsefExporter` (pobranie pliku) → `KsefClient` → **KSeF API**
→ `EncryptionHandler` + `FileDecryptor` (jeśli dotyczy)
→ zapis w `temp/` (opcjonalnie)
→ odpowiedź: streaming ZIP do Browser
(+ logowanie)

##### Wzorce/zasady architektoniczne, które warto nazwać na diagramie
- **Front–Back separation**: statyczny UI i API w PHP.
- **Single entrypoint + Action handlers**: `api.php` jako router, `Actions` jako kontrolery.
- **Strategy pattern dla auth**: `AuthenticatorInterface` + `KsefAuthenticator` + `CertificateAuthenticator`.
- **Ports & adapters / interface-first**: `ExporterInterface`, `LoggerInterface` (łatwiejsza podmiana implementacji).
- **Integration boundary**: `KsefClient` jako adapter do zewnętrznego KSeF.

Dodaj etykiety typu “Strategy”, “Adapter”, “Service” przy komponentach — dla principal-level czytelności.

##### System Context (1 slajd)
- Użytkownik / Przeglądarka
- System “KSeF Import”
- Zewnętrzny “KSeF API”
- Lokalny filesystem (można jako część systemu)

##### Container + Component (1–2 slajdy)
- Container: Browser UI, PHP Backend, File Storage, External KSeF
- Component (wewnątrz backendu): api.php, Actions, KsefService, Auth, Export, KsefClient, Logger

To wystarcza, żeby uchwycić realną architekturę bez “overengineering”.

Wybierz “start_import → check_status → download” jako jeden scenariusz i narysuj sekwencję:
Browser → api.php → Action → KsefService → Auth → KsefClient → KSeF
… potem status … potem download (z decrypt/stream).

Sekwencja często daje większą “prawdziwość” niż statyczny obrazek.

##### Elementy, które masz obowiązkowo umieścić (czytelność + precyzja)
- **Czytelne etykiety** komponentów z nazwami zgodnymi z repo:
- `api.php`, `KsefService`, `KsefClient`, `JsonLogger`, `KsefAuthenticator`, `CertificateAuthenticator`, `KsefExporter`, `FileDecryptor`, `EncryptionHandler`
- **Strzałki kierunkowe** z podpisami protokołu/danych:
- “HTTP (GET/POST)”
- “KSeF REST API via curl”
- “RSA-OAEP + AES-256 (token/file encryption)”
- “ZIP stream to browser”
- **Kolor/kształt wg typu** (proponowana legenda):
- Prostokąty: moduły aplikacji (Actions/Services)
- Cylindry: storage/stan (`logs/`, `temp/`, `last_export_encryption.json`)
- Chmura: zewnętrzny system (KSeF)
- Inny kolor dla “Security/Crypto” (Auth/Encryptor)

##### Co dodatkowo doprecyzować na diagramie (żeby był “maksymalnie komponentowy”)
Ponieważ prosisz o “jak najwięcej komponentów”, rozbij backend na logiczne klocki zamiast jednego bloku:

- `api.php` (Router)
- `Api\Actions\*` (4 osobne boxy)
- `Api\ErrorHandler`
- `KsefService`
- `Auth`:
- `AuthenticatorInterface` (jako adnotacja)
- `KsefAuthenticator`
- `CertificateAuthenticator`
- `TokenEncryptor`
- `keys_cache` (jako storage)
- `Export`:
- `KsefExporter`
- `EncryptionHandler`
- `FileDecryptor`
- `last_export_encryption.json` (storage)
- `Http\KsefClient`
- `Logger\JsonLogger` → `logs/`
- `temp/` (z adnotacją: pliki tymczasowe/ZIP, zabezpieczone `.htaccess`)

##### Gotowy “szkielet” układu diagramu (jak to rozmieścić)
Układ lewo→prawo (czytelny data-flow):
- **Left:** Browser (UI)
- **Center:** PHP Backend (api.php + komponenty)
- **Right:** KSeF API (external)
- **Bottom (pod backendem):** File storage (`temp/`, `logs/`, caches)

To naturalnie pokazuje: UI → API → integracja → pliki/logi → odpowiedź do UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========
  %% Context
  %% =========
  subgraph "System Context"
    U["User"]:::external
    B["Browser (SPA UI)"]:::frontend
    KSEF["KSeF API (DEMO/TEST/PROD)"]:::external
  end

  %% =========
  %% Frontend (static assets)
  %% =========
  subgraph "Frontend (Static Web Assets)"
    FE_INDEX["index.html"]:::frontend
    FE_APP["app.js"]:::frontend
    FE_CSS["styles.css"]:::frontend
  end

  %% =========
  %% Backend (PHP Monolith)
  %% =========
  subgraph "PHP Backend (Monolith)"
    API["api.php (HTTP Entrypoint / Router)"]:::api

    subgraph "API Layer (Actions + Error Handling)"
      EH["Api\\ErrorHandler"]:::api
      HELP["Api\\Helpers"]:::api

      A_START_TOKEN["Api\\Actions\\StartExportAction"]:::api
      A_START_CERT["Api\\Actions\\StartImportWithCertificateAction"]:::api
      A_STATUS["Api\\Actions\\CheckStatusAction"]:::api
      A_DOWNLOAD["Api\\Actions\\DownloadAction"]:::api
      A_RESTART["Api\\Actions\\RestartImportAction"]:::api
    end

    SVC["KsefService (Application Service)"]:::service

    subgraph "Auth Module (Strategy + Crypto)"
      AUTH_I["AuthenticatorInterface (Strategy)"]:::contract
      AUTH_TOKEN["KsefAuthenticator (Token)"]:::security
      AUTH_CERT["CertificateAuthenticator (Certificate/XAdES)"]:::security
      TOK_ENC["TokenEncryptor (RSA-OAEP + AES-256)"]:::security
      AUTH_KEYS[("Auth keys_cache/ (PEM)")]:::storage
    end

    subgraph "Export Module (Exporter + Decrypt)"
      EXP_I["ExporterInterface (Port)"]:::contract
      EXP["KsefExporter (init/status/download)"]:::service
      ENC_META["EncryptionHandler (session keys/metadata)"]:::security
      DEC["FileDecryptor (decrypt downloaded file)"]:::security
      LAST_ENC[("last_export_encryption.json")]:::storage
      EXP_KEYS[("Export keys_cache/ (public_key_*.pem)")]:::storage
    end

    subgraph "HTTP Integration"
      HTTP["Http\\KsefClient (Adapter via curl)"]:::integration
    end

    subgraph "Logging"
      LOG_I["LoggerInterface (Port)"]:::contract
      JLOG["JsonLogger"]:::logging
    end
  end

  %% =========
  %% Local File Storage
  %% =========
  subgraph "Local File Storage"
    TEMP[("temp/ (ZIP + intermediate artifacts)")]:::storage
    HTA["temp/.htaccess (protection)"]:::infra
    LOGS[("logs/ (JSON logs)")]:::storage
  end

  %% =========
  %% Optional docs
  %% =========
  DOCS["docs/ (documentation)"]:::docs

  %% =========
  %% User/UI relationships
  %% =========
  U -->|"uses"| B
  B -->|"loads"| FE_INDEX
  FE_INDEX -->|"references"| FE_CSS
  FE_INDEX -->|"runs"| FE_APP

  %% =========
  %% UI -> API flows (endpoints/actions)
  %% =========
  FE_APP -->|"HTTP POST (action=start_import)"| API
  FE_APP -->|"HTTP POST (action=start_import_certificate)"| API
  FE_APP -->|"HTTP GET (action=check_status)"| API
  FE_APP -->|"HTTP GET (action=download)"| API
  FE_APP -->|"HTTP POST (action=restart_import)"| API

  API -->|"routes"| A_START_TOKEN
  API -->|"routes"| A_START_CERT
  API -->|"routes"| A_STATUS
  API -->|"routes"| A_DOWNLOAD
  API -->|"routes"| A_RESTART
  API -->|"errors"| EH
  API -->|"utils"| HELP

  %% =========
  %% Actions -> Service
  %% =========
  A_START_TOKEN -->|"calls"| SVC
  A_START_CERT -->|"calls"| SVC
  A_STATUS -->|"calls"| SVC
  A_DOWNLOAD -->|"calls"| SVC
  A_RESTART -->|"calls"| SVC

  %% =========
  %% Service orchestration
  %% =========
  SVC -->|"auth (strategy)"| AUTH_I
  AUTH_I -->|"implemented_by"| AUTH_TOKEN
  AUTH_I -->|"implemented_by"| AUTH_CERT

  AUTH_TOKEN -->|"encrypt token"| TOK_ENC
  TOK_ENC -->|"reads/writes keys"| AUTH_KEYS

  SVC -->|"export orchestration"| EXP
  EXP -->|"implements"| EXP_I

  EXP -->|"encryption metadata"| ENC_META
  ENC_META -->|"stores/reads"| LAST_ENC
  ENC_META -->|"reads keys"| EXP_KEYS

  EXP -->|"decrypt (when needed)"| DEC
  DEC -->|"reads metadata"| LAST_ENC
  DEC -->|"writes temp files"| TEMP

  %% =========
  %% Service/Exporter -> HTTP Client -> External
  %% =========
  SVC -->|"KSeF REST API via curl"| HTTP
  EXP -->|"KSeF REST API via curl"| HTTP
  AUTH_TOKEN -->|"KSeF REST API via curl"| HTTP
  AUTH_CERT -->|"KSeF REST API via curl"| HTTP
  HTTP -->|"HTTPS"| KSEF

  %% =========
  %% Download response
  %% =========
  A_DOWNLOAD -->|"ZIP stream to browser"| FE_APP
  EXP -->|"optional ZIP/temp artifacts"| TEMP

  %% =========
  %% Logging
  %% =========
  SVC -->|"log events"| JLOG
  EH -->|"log errors"| JLOG
  JLOG -->|"writes"| LOGS
  JLOG -->|"implements"| LOG_I

  %% =========
  %% Temp security note
  %% =========
  HTA -->|"protects"| TEMP

  %% =========
  %% Docs (non-runtime)
  %% =========
  DOCS -.->|"reference"| FE_INDEX
  DOCS -.->|"reference"| API

  %% =========
  %% Click events (from component mapping)
  %% =========
  click FE_INDEX "https://github.com/poulcuzz/ksef-import/blob/main/index.html"
  click FE_APP "https://github.com/poulcuzz/ksef-import/blob/main/app.js"
  click FE_CSS "https://github.com/poulcuzz/ksef-import/blob/main/styles.css"
  click API "https://github.com/poulcuzz/ksef-import/blob/main/api.php"

  click A_START_TOKEN "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Actions/StartExportAction.php"
  click A_START_CERT "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Actions/StartImportWithCertificateAction.php"
  click A_STATUS "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Actions/CheckStatusAction.php"
  click A_DOWNLOAD "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Actions/DownloadAction.php"
  click A_RESTART "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Actions/RestartImportAction.php"
  click EH "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/ErrorHandler.php"
  click HELP "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/Helpers.php"
  click SVC "https://github.com/poulcuzz/ksef-import/blob/main/src/KsefService.php"

  click AUTH_I "https://github.com/poulcuzz/ksef-import/blob/main/src/Auth/AuthenticatorInterface.php"
  click AUTH_TOKEN "https://github.com/poulcuzz/ksef-import/blob/main/src/Auth/KsefAuthenticator.php"
  click AUTH_CERT "https://github.com/poulcuzz/ksef-import/blob/main/src/Auth/CertificateAuthenticator.php"
  click TOK_ENC "https://github.com/poulcuzz/ksef-import/blob/main/src/Auth/TokenEncryptor.php"
  click AUTH_KEYS "https://github.com/poulcuzz/ksef-import/tree/main/src/Auth/"

  click EXP_I "https://github.com/poulcuzz/ksef-import/blob/main/src/Export/ExporterInterface.php"
  click EXP "https://github.com/poulcuzz/ksef-import/blob/main/src/Export/KsefExporter.php"
  click ENC_META "https://github.com/poulcuzz/ksef-import/blob/main/src/Export/EncryptionHandler.php"
  click DEC "https://github.com/poulcuzz/ksef-import/blob/main/src/Export/FileDecryptor.php"
  click EXP_KEYS "https://github.com/poulcuzz/ksef-import/tree/main/src/Export/"

  click HTTP "https://github.com/poulcuzz/ksef-import/blob/main/src/Http/KsefClient.php"

  click LOG_I "https://github.com/poulcuzz/ksef-import/blob/main/src/Logger/LoggerInterface.php"
  click JLOG "https://github.com/poulcuzz/ksef-import/blob/main/src/Logger/JsonLogger.php"

  click LOGS "https://github.com/poulcuzz/ksef-import/tree/main/logs/"
  click TEMP "https://github.com/poulcuzz/ksef-import/tree/main/temp/"
  click HTA "https://github.com/poulcuzz/ksef-import/blob/main/temp/.htaccess"
  click DOCS "https://github.com/poulcuzz/ksef-import/tree/main/docs/"
  click A_START_TOKEN "https://github.com/poulcuzz/ksef-import/tree/main/src/Api/Actions/"
  click A_START_CERT "https://github.com/poulcuzz/ksef-import/tree/main/src/Api/Actions/"
  click A_STATUS "https://github.com/poulcuzz/ksef-import/tree/main/src/Api/Actions/"
  click A_DOWNLOAD "https://github.com/poulcuzz/ksef-import/tree/main/src/Api/Actions/"
  click A_RESTART "https://github.com/poulcuzz/ksef-import/tree/main/src/Api/Actions/"
  click EH "https://github.com/poulcuzz/ksef-import/blob/main/src/Api/ErrorHandler.php"

  %% =========
  %% Styles
  %% =========
  classDef external fill:#F2F4F7,stroke:#344054,stroke-width:1px,color:#101828
  classDef frontend fill:#E0F2FE,stroke:#0369A1,stroke-width:1px,color:#0B2E4A
  classDef api fill:#EEF2FF,stroke:#4338CA,stroke-width:1px,color:#1E1B4B
  classDef service fill:#ECFDF3,stroke:#027A48,stroke-width:1px,color:#052E16
  classDef integration fill:#FFFBEB,stroke:#B45309,stroke-width:1px,color:#451A03
  classDef security fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#4C0519
  classDef storage fill:#FFFFFF,stroke:#667085,stroke-width:1px,color:#101828
  classDef logging fill:#FDF2FA,stroke:#A21CAF,stroke-width:1px,color:#3B0764
  classDef contract fill:#F1F5F9,stroke:#475569,stroke-dasharray: 4 3,stroke-width:1px,color:#0F172A
  classDef infra fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px,color:#0F172A
  classDef docs fill:#F5F3FF,stroke:#6D28D9,stroke-width:1px,color:#2E1065
```
