Document 6 of 13

Requirements and architecture

Browser, server, network, components, technologies.

For whom: IT

For people who use Orafila

What	Requirement
Browser	Chrome or Edge 111 and later, Firefox 111 and later, Safari 16.4 and later (versions from 2023 onwards), with JavaScript and cookies enabled
Devices	Computer, tablet and phone: the pages adapt to the screen
Two-step verification	A phone with an authenticator app (Google Authenticator, Microsoft Authenticator or similar)
Local installations	None: Orafila is used from the browser
Network	Access to the installation's HTTPS address (for example `https://psa.yourcompany.com`)

For people who install the server

What	Requirement
Operating system	Ubuntu Server 24.04 LTS (also 22.04), 64-bit, x86-64 (amd64) or Arm (arm64) processors
Processor	1 vCPU for a demo, 2 or more recommended
Memory	2 GB or more recommended. With less than 3.5 GB of RAM the preparation script creates 2 GB of spare memory on disk (swap) by itself; building the application needs at least 768 MB of RAM and 2.8 GB of RAM and swap together. 1 GB with swap is enough for a demo
Disk	25 GB for a demo, 50 GB recommended (images, database, local backups); start-up frees the cache by itself when less than 4 GB is left
Public address	A public IPv4 address and a domain name (DNS record of type A pointing to the server) for the HTTPS certificate
Inbound ports	TCP 80 and 443, UDP 443 (HTTPS and HTTP/3); TCP 22 for administration over SSH, preferably only from your IP
Outbound ports	HTTPS 443 (certificates, updates, AI, Fatture in Cloud, backup storage); IMAP 993 (or 143 with STARTTLS); SMTP 465 or 587, or 2525 if the provider blocks the mail ports
Software	Docker Engine with the compose plugin, age, rclone: the preparation script installs them. curl and OpenSSL, which download and check the package, are already in Ubuntu
Access to the package	The HTTPS release address of Orafila and, if the provider uses them, the server's access credentials (also needed for updates)

Providers already tested, with step-by-step guides: Oracle Cloud (Always Free Arm VM, Milan or Frankfurt regions) and DigitalOcean (Droplet, Amsterdam or Frankfurt regions). Any other Ubuntu VPS, for example in the European Union (Aruba, OVHcloud, Hetzner...), works the same way: only the creation of the server and the provider's firewall change.

With an external database (optional)

If the database must be outside the server (a database managed by the cloud provider or the company's own PostgreSQL server):

PostgreSQL 15 or later with TLS, in the same region as the server;
a database dedicated to Orafila, reachable only from the server's IP;
the provider's certificate authority (CA) certificate in PEM format;
a database administrator with permission to create roles and databases (CREATEROLE, CREATEDB; with BYPASSRLS Orafila's backups work too);
at least 25 connections available.

Architecture

                    ┌──────────── Ubuntu server with Docker ───────────────┐
Browser ───HTTPS───►│ Caddy (HTTPS) ──► Orafila app ──┐                   │
                    │                                  ├─► PostgreSQL      │
IMAP/SMTP mailboxes◄┼─► Mail worker ───────────────────┘ (internal network)│
                    │ Migrations (at start-up) · Tools (on request)        │
                    └──────────────────────────────────────────────────────┘
Every night: encrypted backup ──► S3-compatible storage, off the server
Outbound, if enabled: AI providers · Fatture in Cloud (SDI)

Component	What it does
Caddy	Receives visits on ports 80 and 443, obtains and renews the HTTPS certificate by itself (Let's Encrypt), forwards to the app
App	The web application (pages, actions, PDFs, exports, endpoints for e-mails and for the health check)
Mail worker	Reads the queues' IMAP mailboxes every minute, sends queued e-mails via SMTP with retries, asks the AI to triage new tickets
PostgreSQL 16	The database, on an internal network without internet access and without public ports
Migrations	Update the database schema at every start, then stop; the app and the mail worker start only afterwards
Platform operator tools	Activating companies, queue addresses, sample data: commands run on request

A single Docker image for app, mail worker, migrations and tools, built on the server from the source code.
Separate networks: the database is only on the internal network; the app and the mail worker have outbound internet access, which they use for AI, mail and Fatture in Cloud.
Health checks: the app answers on /api/health; the mail worker reports every 15 seconds that it is alive; Docker restarts by itself any service that stops.
Multi-company: a single installation serves several companies, kept separate by the database (see Security and privacy).

Technologies

Layer	Technology
Language	TypeScript in strict mode, on Node.js 22
Web	Next.js 16 (App Router) and React 19, server-side rendering
Database	PostgreSQL (16 in the package, 15 or later supported) with Row-Level Security
Data access	postgres.js with parameterised queries, schema in plain SQL with numbered migrations
Mail	IMAP (imapflow), SMTP (nodemailer), message parsing (mailparser)
PDF	pdf-lib, in pure JavaScript: no browser or external service on the server
AI	Official Anthropic SDK; OpenAI and Google Gemini APIs
E-invoice	Fatture in Cloud API v2
HTTPS	Caddy 2 with Let's Encrypt
Backup	pg_dump, age encryption, copy with rclone to S3-compatible storage
Containers	Docker Engine and Docker Compose

Sizing

A single installation serves several companies. For a pilot company or a demo a server with 2 GB of RAM is enough; with many companies or many concurrent users you increase the memory and processors of the same server (the services' memory limits are: database 2 GB, app 2 GB, mail worker 1 GB, Caddy 256 MB). With an external database the database load moves to its own server.