Architecture — Plik (System-Wide) ​

High-level architecture, package layering, data flows, and API reference for the entire Plik system. For sub-package details, see the scoped ARCHITECTURE.md in each root folder.

System Overview ​

Plik is a temporary file upload system with three main components:

Core Abstractions ​

High-Level Architecture ​

Package Layering ​

Dependency direction flows left to right. Packages only import from packages to their left.

common → context → metadata/data → middleware → handlers → cmd → server

Request Lifecycle ​

Every HTTP request flows through a middleware chain before reaching a handler:

Middleware Chains ​

The server defines several middleware chains composed from individual middlewares:

File Status State Machine ​

Files transition through these statuses during their lifecycle:

Limits & User Quota Overrides ​

Plik enforces limits at two levels: server-wide defaults (from config) and per-user overrides (stored on the User model, set by admins).

Server-Level Limits (config) ​

Per-User Overrides ​

Each User has three quota fields that can be set by an admin (via POST /user/{userID} or plikd user update CLI):

Special Values ​

Resolution Order ​

When processing a request, limits are resolved via the custom Context:

1. MaxFileSize (Context.GetMaxFileSize()): if user.MaxFileSize != 0, use it; otherwise fall back to config.MaxFileSize
2. MaxUserSize (Context.GetUserMaxSize()): if user.MaxUserSize > 0, use that cap; if user.MaxUserSize < 0, unlimited; if 0, fall back to config.MaxUserSize. Only applies to authenticated users — anonymous uploads have no user size limit.
3. MaxTTL (in Context.setTTL()): if user.MaxTTL != 0, use it; otherwise fall back to config.MaxTTL. When maxTTL > 0, infinite TTL is rejected and requested TTL is capped.

Note: Anonymous uploads (no token/session) use server defaults directly. Per-user overrides can be more permissive or more restrictive than server defaults — there is no "admin can only restrict" rule.

Public Endpoints (open — no auth required) ​

Upload & File Endpoints (token chain — session cookie or X-PlikToken header) ​

Authentication Endpoints ​

User Endpoints (authenticated — session cookie required) ​

User Management Endpoints (authenticated — session cookie required) ​

Admin Endpoints (admin only — session cookie + admin flag) ​

Authentication Flows ​

Session Cookie Authentication ​

1. User authenticates via /auth/{provider}/login → consent URL → /auth/{provider}/callback
2. Server creates JWT session cookie (plik-session) signed with server-generated key
3. XSRF cookie (plik-xsrf) must be echoed in X-XSRFToken header for mutating requests
4. Cookies are Secure when EnhancedWebSecurity is enabled

Upload Token (per-upload) ​

1. Every upload gets a random UploadToken on creation (returned in the POST /upload response)
2. The token grants admin-like access to that specific upload — add files, remove files, delete the upload
3. This enables anonymous (non-authenticated) uploads: whoever holds the token controls the upload
4. Sent in the X-UploadToken header for subsequent requests on that upload

CLI Token (per-user) ​

1. Authenticated user creates a CLI token via POST /me/token
2. Token (UUID) sent in X-PlikToken header or stored in .plikrc config
3. Authenticates CLI clients on behalf of a user — uploads are linked to the user's account for quota tracking

CLI Device Auth Flow ​

1. CLI calls POST /auth/cli/init with hostname → receives a code, secret, and verification URL
2. User opens the verification URL in their browser and approves the login (requires session cookie)
3. CLI polls POST /auth/cli/poll with code + secret → receives the generated token once approved
4. Token is automatically saved to ~/.plikrc — identical to tokens created via POST /me/token
5. Sessions are ephemeral (5 min TTL), one-time use, and cleaned by the background routine

Auth Providers ​

Configuration Model ​

TOML File (plikd.cfg) ​

Server configuration is a TOML file. See server/plikd.cfg for all options with inline comments.

Environment Variable Override ​

Any config parameter can be overridden via env var using SCREAMING_SNAKE_CASE with PLIKD_ prefix:

PLIKD_DEBUG_REQUESTS=true ./plikd
PLIKD_DATA_BACKEND_CONFIG='{"Directory":"/var/files"}' ./plikd

Arrays are overridden, maps are merged.

Helm Chart Sync ​

The Helm chart (charts/plik/) mirrors the configuration model. When adding or modifying config fields in server/common/config.go or server/plikd.cfg, always update:

• charts/plik/values.yaml — add the field under plikd: with its default value
• charts/plik/templates/configmap.yaml — add the explicit key to the template
• charts/plik/templates/secret.yaml — if the field is sensitive, add env var injection (PLIKD_ prefix)

Helm Chart Persistence ​

The chart supports two independent PVCs:

Both are disabled by default (enabled: false) and fall back to emptyDir when disabled. For StatefulSet kind, both create volumeClaimTemplates (always provisioned). The default MetadataBackendConfig.ConnectionString is /home/plik/server/db/plik.db — this path is valid even without a PVC (the directory is created at runtime).

Feature Flags ​

Special Values ​

Data Backend Interface ​

type Backend interface {
    AddFile(file *common.File, reader io.Reader) (err error)
    GetFile(file *common.File) (reader io.ReadCloser, err error)
    RemoveFile(file *common.File) (err error)  // must not fail if file not found
}

Implementations ​

GORM-based with auto-migrations via gormigrate.

Tables ​

Documentation ​

Plik maintains two layers of documentation for different audiences:

Human-Readable Docs (docs/) ​

A VitePress site deployed to GitHub Pages. Built with Vue 3 and Vite.

docs/
├── .vitepress/config.js   ← site config (nav, sidebar, search)
├── index.md               ← landing page (hero + features)
├── guide/                 ← getting started, configuration, security
├── features/              ← CLI client, web UI, authentication
├── backends/              ← data and metadata backend setup
├── reference/             ← HTTP API, Prometheus metrics, Go library
├── operations/            ← reverse proxy, cross-compilation
├── architecture/          ← links to in-repo ARCHITECTURE.md files
└── contributing.md        ← dev setup and build instructions

• Build: make docs (or cd docs && npm run dev for local dev server)
• Deploy: Automated via .github/workflows/pages.yml on push to master (also publishes the Helm chart via chart-releaser)
• CI: Build is verified on every push/PR via .github/workflows/tests.yaml. Automated docker build (docker build comment) and deploy (docker deploy comment) are available on PRs.

Build pipeline (make docs):

1. inject_version.sh — replaces __VERSION__ placeholders in markdown files with the current version from gen_build_info.sh. Only runs in CI ($CI env var); skipped locally to avoid dirtying source files.
2. copy_architecture.sh — copies each ARCHITECTURE.md from the repo into docs/architecture/ with cross-link rewriting. These generated files are .gitignored.
3. npm run build — runs the VitePress build (includes dead link checking).

Agent-Readable Docs (ARCHITECTURE.md files) ​

Scoped ARCHITECTURE.md files placed in each package directory, designed for AI coding assistants. Each file documents internal structure, key abstractions, data flow, and design decisions. See the list below.

Changelog (changelog/) ​

One file per version tag (e.g., changelog/1.3.8). Used by gen_build_info.sh to build the release history exposed via GET /version and displayed in the web UI's update notification.

Scoped Architecture Docs ​

For deeper details on each component:

• server/ARCHITECTURE.md — Server internals
• client/ARCHITECTURE.md — CLI client
• plik/ARCHITECTURE.md — Go library
• webapp/ARCHITECTURE.md — Vue 3 SPA
• testing/ARCHITECTURE.md — Backend integration tests
• releaser/ARCHITECTURE.md — Release pipeline
• .github/ARCHITECTURE.md — GitHub Actions workflows & CI/CD