profilarr/docs/CONTRIBUTING.md

Contributing to Profilarr

Profilarr is a work-in-progress rewrite, so please coordinate larger changes first. This guide explains how the repo is organized and the expected contribution workflows.

Project Overview

Profilarr is a SvelteKit + Deno app that manages and syncs configurations across *arr apps using Profilarr Compliant Databases (PCDs). It compiles to standalone binaries.

• Frontend: src/routes/, src/lib/client/
• Backend: src/lib/server/
• PCDs: git repositories cloned under data/databases/ and compiled into an in-memory SQLite cache

Prerequisites

• Deno 2.x
• Node + npm only if you want to run ESLint/Prettier (deno task lint or deno task format).
• .NET 8 only if you work on the parser microservice in services/parser/.

Development Commands

• deno task dev (default port 6969)
• deno task test
• deno task lint
• deno task format

Useful environment variables:

• APP_BASE_PATH (defaults to the compiled binary location)
• PARSER_HOST, PARSER_PORT (C# parser microservice)
• PORT, HOST

Repo Tour

• docs/ARCHITECTURE.md — system overview
• docs/PCD SPEC.md — operational SQL & layering model
• docs/manifest.md — pcd.json schema
• docs/PARSER_PORT_DESIGN.md — parser microservice
• services/parser/ — C# parser microservice

App Database vs PCD Databases

Profilarr app database

• SQLite file: data/profilarr.db
• Boot sequence initializes config, opens DB, runs migrations, starts job system.
• Migrations live in src/lib/server/db/migrations/ and are run on startup.

PCD databases

• Git repos cloned into data/databases/<uuid>.
• Compiled into an in-memory SQLite cache (PCDCache) using ordered SQL operations.
• Layers in order: schema → base → tweaks → user.
• SQL helper functions available inside PCD ops: qp, cf, dp, tag.

Adding a Migration

1. Copy src/lib/server/db/migrations/_template.ts to a new file like 021_add_foo.ts.
2. Update version and name, then fill out up SQL and (ideally) down SQL.
3. Add a static import in src/lib/server/db/migrations.ts.
4. Add the new migration to loadMigrations() (keep sequential ordering).

Notes:

• Versions must be unique and sequential.
• Never edit an applied migration; create a new one instead.
• Migrations run automatically on server startup.

Working with PCDs

PCD layout

my-pcd/
├── pcd.json
├── ops/
└── tweaks/

Authoring operations

• Follow the append-only Operational SQL approach.
• Use expected-value guards in UPDATE statements to surface conflicts.
• New ops go in ops/ or tweaks/ depending on intent.

User ops

Profilarr writes user edits via src/lib/server/pcd/writer.ts into user_ops/, rebuilding the in-memory cache after write.

Client UI Components

Shared UI lives in src/lib/client/ui/. Route-specific components live next to their routes.

Alerts and toasts

• Store: src/lib/client/alerts/store.ts
• Use the alert store for success/error/info toasts in enhance actions and API responses.

Actions and toolbars

• src/lib/client/ui/actions/ActionsBar.svelte
• src/lib/client/ui/actions/ActionButton.svelte
• src/lib/client/ui/actions/SearchAction.svelte
• src/lib/client/ui/actions/ViewToggle.svelte

Dropdowns

• src/lib/client/ui/dropdown/Dropdown.svelte
• src/lib/client/ui/dropdown/DropdownItem.svelte

Buttons

• src/lib/client/ui/button/Button.svelte (variants + sizes)

Forms

• FormInput, NumberInput, TagInput, IconCheckbox

Tables and lists

• Table, ExpandableTable, ReorderableList

Modals

• Modal, SaveTargetModal, UnsavedChangesModal, InfoModal

Navigation

• navbar, pageNav, tabs

State and empty views

• EmptyState

Svelte Conventions

• Use Svelte 4 syntax (export let, $:) even though Svelte 5 is installed.
• Avoid Svelte 5 runes unless explicitly used in that module.
• Route-specific components should be colocated under their route directory.

Tests

• Tests live in src/tests/ and run with deno task test.
• Base test utilities are in src/tests/base/BaseTest.ts.
• Many tests create temp dirs under /tmp/profilarr-tests.

Parser Microservice (Optional)

If you touch parser-related code, see docs/PARSER_PORT_DESIGN.md and services/parser/.

• dotnet run from services/parser/
• Configure PARSER_HOST / PARSER_PORT in Profilarr