Fulgoria documentation

Fulgoria extracts structured data from documents that were designed to be read, not parsed. You teach it a layout once by marking columns; from then on it reads every document of that kind and gives you clean CSV. Everything below happens in your browser.

The flow

1. Open a document

Click Open PDF or image and choose a file, or pick See an example to load a sample bank statement. Digital PDFs and scans or photos are both accepted. Scans and images are read with local OCR (Tesseract.js), so even an image of a statement becomes text without leaving your machine.

2. Mark the columns

Fulgoria auto-detects the columns as a first pass. You refine them by dragging over the document to say where each datum lives. Then assign a role to each column:

• date — the transaction date
• description — the concept or payee
• debit / credit / amount with sign — the movement value
• balance — the running balance
• text — any other column you want to keep

You can also apply free, Excel-style formatting per column (date and number patterns, WYSIWYG) and set exclusion rules by content to skip repeated headers, “TOTALS” rows and similar noise.

The balance rule

For bank statements Fulgoria checks opening + credits − debits == closing. When it holds, the card turns green — a fully local, arithmetic confirmation that the columns were read correctly. No voting, no guesswork to trust.

3. Edit before exporting

A spreadsheet-style editor lets you fix any cell, with the balance recomputing live. It supports find & replace, adding and deleting rows, pasting from Excel, undo/redo, fill-down, assisted categorization, quality flags, and editable opening/closing values.

4. Export

When the data is clean, export it:

• CSV — the movements, ready for a spreadsheet or your accounting tool.
• Template — the geometry as a reusable .ext.json or .ext.yaml file (see below).
• Send to Escriba — hand the clean result to your local Escriba.

Supported formats

Input

Digital PDFs and scans / images (PNG, JPG and similar). Multi-page documents and multi-account PDFs — for example pesos and dollars in one file — produce one card per account.

Output

CSV for the movements, and template files in .ext.json or .ext.yaml for the layout. A “Send to Escriba” handoff passes the result to the rest of the suite.

Reusable templates

The first time you mark a bank’s statement, Fulgoria can save that layout as a template. Next time you open a document of the same kind, it is recognized automatically and the columns are already in place — no re-marking.

Templates store shape, not data

A template records where each datum is (the geometry), never what it says. Sharing a template shares the document’s structure, not its contents — so it is safe to pass around.

Templates can be loaded from a downloaded .json file or chosen from your saved templates inside the app.

Privacy: local-first by design

Everything runs in your browser. The PDF is opened, read and processed inside your machine, and there is not a single external request — fonts and libraries are vendored into the app. Privacy is not a feature bolted on; it is the architecture.

When Fulgoria is self-hosted, the thin server still never receives the document. It only serves the static files and handles the optional login. It applies a strict CSP and security headers, and never exposes .env, server.js or any private samples.

The server and login

For production, Fulgoria ships a thin server (server.js, Node/Express) whose only jobs are serving the static app and gating it behind an optional login read from .env.

With login

Set AUTH_ENABLED=true and configure AUTH_USER and AUTH_PASSWORD. Sessions are signed with SESSION_SECRET and last SESSION_TTL_HOURS hours. Behind HTTPS, keep COOKIE_SECURE=true.

Without login

Set AUTH_ENABLED=false to serve the app with no password — convenient for local use or a trusted private network.

Generate a bcrypt password hash and a session secret like this:

node server.js --hash 'your-password'   # → AUTH_PASSWORD
openssl rand -hex 32                     # → SESSION_SECRET

Configuration reference

All settings live in .env:

Variable	Default	Purpose
PORT	3000	Server port.
AUTH_ENABLED	true	Toggle the login on or off.
AUTH_USER	diego	Login username.
AUTH_PASSWORD	(empty)	Plain-text password or bcrypt hash.
SESSION_SECRET	(empty)	Signs the session cookie.
SESSION_TTL_HOURS	12	Session lifetime in hours.
COOKIE_SECURE	true	true behind HTTPS, false for local http://.
ESCRIBA_URL	(empty)	Target of “Send to Escriba”; empty falls back to /.

Note

See the installation guide for full Docker, compose and EasyPanel instructions.