A web application for generating pre-filled Polish social insurance (ZUS) Z-15A forms. It stores records for caretakers, children, jobs, and leaves, and can produce a completed PDF form and deliver it by e-mail.

• Purpose
• Architecture
• Repository structure
• Tech stack
• Getting started
  • Prerequisites
  • Install dependencies
  • Run in development mode
• Available scripts
• Environment variables
• Docker deployment
• CI/CD
• Versioning

The Z-15A form is used to claim a care allowance from the Polish Social Insurance Institution (ZUS) when a parent or guardian is unable to work due to caring for a sick child. This application provides:

• A persistent store (SQLite) for caretakers, children, jobs (ZUS payers), and leaves (absences).
• A REST API that generates a fully pre-filled Z-15A PDF from the stored data.
• An option to send the generated PDF directly by e-mail.
• A React single-page application that lets users manage their data and trigger PDF generation from a browser.

┌──────────────────────────────────────────────────────────────────┐
│                    Browser (React SPA)                           │
│  packages/frontend  –  port 3000 (dev) / nginx (production)      │
│                                                                  │
│  Tabs: Leaves · Caretakers · Kids · Jobs                         │
│  Redux Toolkit + RTK Query  ──►  REST API calls (/api/*)         │
└──────────────────────┬───────────────────────────────────────────┘
                       │  HTTP  (proxied to :4000 in dev)
┌──────────────────────▼───────────────────────────────────────────┐
│                  Fastify REST API                                │
│  packages/backend  –  port 4000                                  │
│                                                                  │
│  Routes:                                                         │
│    GET/POST  /kids        – child records                        │
│    GET/POST  /leaves      – absence records                      │
│    GET/POST  /jobs        – employer records                     │
│    GET/POST  /caretakers  – guardian records                     │
│    POST      /pdf         – generate & e-mail Z-15A PDF          │
│    GET       /health      – liveness probe                       │
│                                                                  │
│  Zod validation · Drizzle ORM · pdf-lib · Nodemailer             │
└──────────────────────┬───────────────────────────────────────────┘
                       │
               SQLite database
       (better-sqlite3 + Drizzle ORM)

In production both packages are built and deployed to a VPS via GitHub Actions:

• The frontend dist/ is served by nginx:alpine.
• The backend dist/ runs inside a node:24-alpine container.
• Both containers share a Docker network called apps.

dtrw-app-z15a/
├── packages/
│   ├── backend/       # Fastify API server
│   └── frontend/      # React SPA (Vite)
├── docker/
│   ├── backend/env    # Docker env-file template for the backend
│   └── frontend/      # nginx config for the SPA
├── docker-compose.yml # Production orchestration
├── package.json       # Root scripts & workspace definitions
└── CHANGELOG.md       # Auto-generated version history

Each package has its own README.md with package-specific details:

• packages/backend/README.md
• packages/frontend/README.md

• Node.js ≥ 24 (node --version)
• Yarn (npm install -g yarn)

yarn install

yarn dev

This starts both the frontend dev server (http://localhost:3000) and the backend API server (http://localhost:4000) concurrently. The Vite dev server proxies /api requests to the backend automatically.

Note: The backend requires environment variables for e-mail and the database path. Copy docker/backend/env to packages/backend/.env and fill in the values before running. See Environment variables for details.

All scripts can be run from the repository root using Yarn, which delegates to each package.

See the package READMEs for package-specific scripts.

The backend reads its configuration from environment variables (validated at startup with Zod):

In Docker the variables are supplied via docker/backend/env and an optional .env.backend file.

The docker-compose.yml at the repository root is used for production deployments. Before using it, build both packages first:

yarn build

Then copy the build artefacts to the expected locations and start the services:

# build artefacts are copied to ./frontend and ./backend by the deploy workflow
docker compose up -d

The frontend container serves the React app on port 80 via nginx. The backend container exposes port 4000 internally on the apps Docker network (not published to the host).

Three GitHub Actions workflows are defined in .github/workflows/:

The project uses Conventional Commits (enforced by Husky + commitlint) and standard-version for automated changelog generation and semantic version bumping. Each package is versioned independently.