mirror of
https://github.com/Dictionarry-Hub/profilarr.git
synced 2026-01-23 19:21:12 +01:00
74b38df686
- Created EntityTable component for displaying test entities with expandable rows for releases. - Implemented ReleaseTable component to manage and display test releases with actions for editing and deleting. - Added ReleaseModal component for creating and editing releases - Introduced types for TestEntity, TestRelease, and related evaluations - Enhanced general settings page to include TMDB API configuration with connection testing functionality. - Added TMDBSettings component for managing TMDB API access token with reset and test connection features.
152 lines
4.4 KiB
Markdown
152 lines
4.4 KiB
Markdown
# 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
|