Developer Guide

Welcome to the DBackup Developer Guide. This section covers architecture, contribution guidelines, and how to extend the application.

Overview

DBackup is built with:

• Frontend: Next.js 16 (App Router), React, TypeScript
• UI Components: Shadcn UI
• Styling: Tailwind CSS
• Database: SQLite via Prisma ORM
• Authentication: better-auth

Project Structure

src/
├── app/              # Next.js App Router
│   ├── actions/      # Server Actions
│   ├── api/          # API routes
│   └── dashboard/    # Dashboard pages
├── components/       # React components
├── lib/
│   ├── adapters/     # Database, Storage, Notification adapters
│   ├── core/         # Interfaces and types
│   └── runner/       # Backup execution pipeline
└── services/         # Business logic layer

Quick Start

Prerequisites

• Node.js 24
• pnpm 10
• Docker (for testing)

Setup

# Clone repository
git clone https://github.com/Skyfay/DBackup.git
cd DBackup

# Work from dev, which holds everything finished since the last release
git checkout dev

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start development server, which applies the database migrations first
pnpm dev

Open http://localhost:3000.

Testing

# Run unit tests
pnpm test

# Start the dev lab and fill the dev database with it, see Dev Lab
pnpm lab:up && pnpm lab:seed

Architecture Principles

Four-Layer Architecture

1. App Router (src/app) - Route definitions only
2. Service Layer (src/services) - Business logic
3. Adapter System (src/lib/adapters) - External integrations
4. Runner Pipeline (src/lib/runner) - Backup execution

Key Rules

• Server Actions delegate to Services - No business logic in actions
• Adapters are pluggable - Follow interface contracts
• Streaming architecture - Efficient memory usage
• SSH exec over tunneling - Database tools run remotely via SSH, output streams back
• Permission checks everywhere - RBAC enforcement

Contributing

Branches and Pull Requests

Branch	What it holds
main	The released code. Each release merges dev into main and is tagged vX.Y.Z
dev	Everything that is finished, waiting for the next release
Feature branches	One feature or fix each, branched off dev

Pull requests go into dev, never into main. Only the maintainer merges dev into main for a release.

git checkout dev
git pull
git checkout -b feat/short-description
# ... commit your work
git push -u origin feat/short-description
# then open the pull request with dev as its base

Every pull request into dev or main runs lint, type check, unit tests and the docs build.

Releasing

Only the maintainer releases, from an up to date dev. pnpm toolbox lists every command used here in one menu, each also runs on its own:

1. pnpm version:bump checks the changelog fragments and asks GitHub for the CodeQL alerts open on dev that main does not have. While one is open, it asks whether to go on. Then it picks the next version, writes its block into docs/changelog.md and sets the version everywhere. pnpm codeql:check runs the CodeQL part on its own.
2. Replace *Release: In Progress* with *Released: <date>*, commit, push dev and open the pull request from dev into main. Merge it with a merge commit, not a squash, so both branches keep their history. A change that still belongs to the release after the bump gets its fragment as usual, and pnpm changelog:amend adds it to the block.
3. pnpm release:tag proposes the tag of the version on main, with the title from the changelog as its message, and pushes it once you confirm. The tag starts the release workflow. pnpm release:untag deletes a tag here and on GitHub, so a release that failed can be tagged again.

Code Style

• TypeScript strict mode
• ESLint configuration
• kebab-case file names

PR Guidelines

1. Create a feature branch off dev
2. Write tests for new features
3. Update documentation
4. Run pnpm validate and pnpm run build before submitting
5. Open the pull request against dev

Security vulnerabilities are never reported in a pull request or an issue. See SECURITY.md.

Commit Messages

Follow conventional commits:

feat: add MongoDB adapter
fix: correct retention calculation
docs: update API documentation

Key Documentation

• Architecture - System design details
• Adapter System - How adapters work
• Runner Pipeline - Backup execution flow
• Icon System - Iconify icon mapping for adapters
• Logging System - System logger, custom errors, execution logs
• Download Tokens - Temporary download links for wget/curl
• Checksum & Integrity - SHA-256 verification throughout the backup lifecycle
• Testing Guide - Writing tests

Package Manager

Always use pnpm:

pnpm install
pnpm add package-name
pnpm test

Environment Variables

See Environment Reference for all variables and Installation Guide for Docker setup.