Calibra Fácil

Open-source management software for calibration laboratories working under ISO/IEC 17025: calibration workflow, GUM uncertainty calculations, certificates with review/approval and ICP-Brasil digital signatures, a client portal, and a desktop app that keeps working offline.

Em português: o Calibra Fácil é um software de código aberto (licença MIT) para laboratórios de calibração sob a ISO/IEC 17025 e oficinas permissionárias do Inmetro. Cobre o fluxo de calibração, o cálculo de incerteza conforme o GUM, certificados com revisão e aprovação assinados em ICP-Brasil, o portal do cliente e um aplicativo desktop que funciona offline. A interface é em português; o código e a documentação técnica, em inglês. Para rodar localmente, siga o Quick start.

Calibra Fácil started as a commercial SaaS used in production by accredited laboratories in Brazil. It is now maintained as an open-source project, on a best-effort basis, by its community.

No warranty. The software is provided "as is" under the MIT License. Each laboratory is solely responsible for validating it for its own use (ISO/IEC 17025:2017 §7.2.2 and §7.11) and for the results and certificates it issues. The validation dossiers are technical references, not approvals.

Features

• Calibration workflow — draft → execution → technical review → approval, with distinct roles, an immutable approved version and amendments that keep the history.
• GUM uncertainty engine (packages/math-engine) — exact decimal arithmetic, Type A/B evaluation, correlated inputs, Welch–Satterthwaite with Student-t coverage, reproducible SHA-256 calculation fingerprints and versioned validation dossiers.
• Method catalog — guide-grounded calibration methods (mass, force, frequency, electrical DC, volume, humidity, weighing instruments) compiled from declarative definitions with dimensional checks.
• Certificates — PDF certificates following ISO/IEC 17025 §7.8, PAdES signatures with an ICP-Brasil A1 certificate, public verification page and QR codes.
• Traceability & quality — reference standards with validity control, personnel competence, non-conformities/CAPA, proficiency tests, SPC charts and calibration-interval analysis.
• Legal metrology — Inmetro regulation catalog, repair seals and delivery receipts for "oficinas permissionárias".
• Operations — customers, assets, service orders, quotes, on-site visits, thermal label printing (ZPL/TSPL) and optional ERP integration (Conta Azul).
• Client portal — customers see their instruments, due dates and certificates, request calibrations and approve quotes; custom domains and lab branding.
• Desktop app — Electron shell with a local SQLite server, an outbox and conflict resolution, so field work continues offline and syncs later.

Architecture

            ┌───────────────┐   ┌───────────────┐   ┌──────────────────────────┐
browser ──▶ │  apps/web     │   │  apps/portal  │   │  apps/desktop            │
            │  lab app      │   │  client portal│   │  Electron + local-server │
            └───────┬───────┘   └───────┬───────┘   │  (SQLite, offline sync)  │
                    │                   │           └────────────┬─────────────┘
                    └─────────┬─────────┴────────────────────────┘
                              ▼
                    ┌───────────────────┐        ┌──────────────────────┐
                    │  apps/api (Hono)  │ ─────▶ │  apps/worker         │
                    │  REST + auth      │  jobs  │  PDFs, e-mails, syncs│
                    └─────────┬─────────┘        └──────────┬───────────┘
                              │                             │
          ┌───────────────────┼───────────────┬─────────────┴──────┐
          ▼                   ▼               ▼                    ▼
     PostgreSQL       S3-compatible      Gotenberg            SMTP or Resend
     (Drizzle)        object storage     (HTML → PDF)         (e-mail)

Path	What it is
apps/api	Hono API: REST routes, Better Auth, cron handlers
apps/web	Lab app (React 19, Vite, TanStack Router/Query, Tailwind 4)
apps/portal	Client portal
apps/worker	Background jobs: certificate PDFs, signing, e-mails, integrations
apps/desktop	Electron desktop shell
apps/local-server	Local API for the desktop app, backed by SQLite
apps/docs	User documentation (Fumadocs on Next.js)
apps/site	Project website (static Vite build, served by Cloudflare)
packages/math-engine	GUM uncertainty engine (versioned, with validation dossiers)
packages/db	Drizzle schema, SQL migrations and seeds
packages/auth	Better Auth configuration, roles and permissions
packages/signing	PAdES/ICP-Brasil certificate signing
packages/local-db	Offline SQLite store, outbox and conflict records
packages/*	Contracts, client SDK, schemas, documents, e-mail, notifications…

Architecture rules worth reading before a first change: CLAUDE.md (big picture), docs/architecture/api-client-contract.md and docs/architecture/web-frontend-architecture.md.

Quick start

Requirements: Node.js 24, pnpm 11 (corepack enable), Bun 1.x and Docker with the Compose plugin. No cloud account is needed.

git clone https://github.com/CalibraFacil/calibrafacil.git
cd calibrafacil
pnpm install
pnpm setup:dev   # env files, Docker services, migrations, demo laboratory
pnpm dev         # API :3000, lab app :5173, portal :5174

Then open http://localhost:5173 and sign in as [email protected]. Sign-in is passwordless: the magic link arrives in the local inbox at http://localhost:8025. The seed also creates [email protected] (admin) and [email protected] (technician), so review and approval flows that need two people can be exercised. The client portal at http://localhost:5174 signs in each demo customer's contact the same way, for example [email protected].

The demo laboratory is not empty: setup fills it with a made-up customer base, instrument park, about 130 calibrations across every workflow stage, quality records, service orders, requests and visits, so the dashboard looks like a working lab. The 40 most recent approvals come with their certificate PDF (--all-certificates renders every one). It takes about two minutes (pnpm setup:dev --no-demo skips it; pnpm --dir apps/api seed:demo runs it later, --quick for a smaller history). All names, e-mails and documents are fictional.

docker-compose.yml stands in for every cloud dependency:

Service	Replaces	Address
postgres	managed PostgreSQL	localhost:55432
s3	Cloudflare R2 / S3	http://localhost:59000
mailpit	SMTP server + inbox for e-mails	http://localhost:8025 (SMTP :1025)
gotenberg	PDF rendering	http://localhost:3001

pnpm services:down stops the containers (data is kept); pnpm setup:dev --reset wipes them and starts over.

Or skip the local setup: The dev container (.devcontainer/) installs everything and seeds the demo laboratory; run pnpm dev and open the forwarded port 5173.

Development

pnpm dev              # API, lab app and portal
pnpm dev:all          # every app with a dev script (docs, site, desktop, worker…)
pnpm lint             # oxlint (architecture boundaries are lint rules too)
pnpm format           # Prettier
pnpm check-types      # TypeScript (tsrs; pnpm check-types:tsc for native tsc 7)
TZ=UTC pnpm turbo test                      # unit tests
pnpm --dir apps/api test:integration        # real-Postgres integration tests (Docker)
pnpm --dir apps/web test:stack              # browser checks against a running `pnpm dev`

Database migrations are plain SQL in packages/db/drizzle/; apply them with pnpm --dir packages/db db:bootstrap (a new database is built from the schema; an existing one receives the pending migrations). The real-Postgres integration tests run in CI after every merge to main and nightly.

Self-hosting

One server with Docker runs the whole system, HTTPS included:

git clone --depth 1 https://github.com/CalibraFacil/calibrafacil.git
cd calibrafacil/deploy
./setup.sh               # .env with fresh secrets; then set your domains and SMTP in it
docker compose up -d
docker compose exec api bun src/cli/create-lab.ts --name "Meu Laboratório" --email [email protected]

Images for x86-64 and ARM64 are published with every release. DEPLOYMENT.md covers updates, backups, hosted databases and storage, plain Bun servers.

Contributing

Bug reports, fixes, calibration methods and documentation are welcome. Read CONTRIBUTING.md first; questions go to GitHub Discussions. Security issues: see SECURITY.md.

License

MIT © 2025–2026 Pedro Seibel and the Calibra Fácil contributors.