←~/progetti/formicaio/README.md

Formicaio

{ “date”: “2026-10-24”, “status”: “live”, “stack_modules”: 14 }

A team of specialised agents for your everyday goals — they remember the context, cite their sources and measure progress

</>Visit the official site!↗

Formicaio started from a question I asked myself every morning: 'what can I eat this morning?'. Answering it well takes the training plan, the day of the week, what is in the cupboard and the goal — and with a generic AI chat all of it had to be explained from scratch, every single time: a quarter of an hour to decide on a meal, only to get advice that knew nothing about me. Formicaio starts from the opposite assumption: context is structured data, not text to be rewritten. It is a personal assistant made of specialised agents, grouped in teams — athletics, study, any other area — that answer in a few seconds with your context, say which source each piece of advice comes from, and keep count of what you actually do.

## Teams, agents and sources

A team is an area with its own shared state: goals, metrics, recurring commitments, observation types. Inside it there are one or more agents, each with its own instructions, principles and documents. Before every answer, a structured reading of the question picks the agent that should answer and recognises what needs to be recorded; then the agent answers, citing the passages its advice comes from.

·Documents per agent, split into passages and found with PostgreSQL full-text search: every citation points to the exact passage

·Observations read from the chat: a skipped session, a weigh-in or a meal become data, validated by the core, with no forms to fill in

·Recurring commitments, such as the week's training sessions, with the exceptions mentioned in the chat

·Every answer is a recommendation for a specific day: one tap under the answer says how it went, and that is where adherence is measured

## A core that knows nothing about athletics

The strictest requirement was agnosticism: a new area has to be added through configuration alone, without touching the code. The core knows neither the track nor the exams, and a CI check fails if a pilot term shows up in its modules. A team's configuration is described by a versioned JSON Schema and validated with Ajv; every save publishes a new immutable version, and every turn records the one it used. The second team, study, was born that way: one configuration file, zero lines of code. Today teams, agents, metrics and observation types are created and edited straight from the app, starting from templates.

## The turn, from question to answer

Every question is a turn with a complete trace: the configuration version, the context sent to the model, the attempts, the rule checks, the tokens and the cost. The context is assembled by reading the core in the same process, because within a turn the system has to read its own writes: that is the main reason the architecture is a modular monolith and not a set of services.

·Modular monolith with hard boundaries: one public interface per module, one PostgreSQL schema and one database role per module, dependencies checked in CI with dependency-cruiser

·Events enqueued in the same transaction as the turn and delivered once by graphile-worker, dead-lettered after three attempts

·A daily spending cap per user, reserved under an advisory lock before the model is called

·The text of questions and answers is deleted after 90 days: dates, durations, costs and a hash remain

## Your key, your model

Formicaio has no key of its own. Each user picks the provider in Settings — Anthropic, OpenAI or DeepSeek — and pastes their own key, which is sealed with AES-256-GCM in a separate schema. There is one model per provider, behind a common adapter with its own retry loop inside the turn's latency budget. Every answer is paid for by whoever asks, and before choosing, the app states plainly how each provider treats data.

## Measure, don't guess

The project has a weekly gate with two numbers: adherence, the share of commitment days on which the advice is actually followed (the target is at least 80%), and the time from question to answer shown (p95 under two minutes, against the quarter of an hour it started from). Answer quality is evaluated on a frozen set of questions, on a throwaway copy of the database, never in production.

## Design and visual identity

The app is an installable PWA, built for the phone but comfortable on the desktop too, with a soft look and a single blue as its primary colour. The mark is an anthill in section: the mound on top, the chambers inside, the galleries cut out down to the entrance, so the ground shows through on any surface. In the name, the 'AI' of FORMICAIO is in the accent colour.

·HeroUI v3 themed with Formicaio's tokens, light and dark

·Plus Jakarta Sans served by the app itself: no requests to external font services

·Passwordless sign-in with an email and a six-digit code, built on Clerk's APIs with the app's own markup

·Markdown answers rendered safely, with numbered citations; every public page is checked with axe-core in the tests

## Tech stack

A TypeScript monorepo managed with pnpm: the backend, the PWA and an API client generated from the backend's OpenAPI contract, so front end and back end cannot drift apart silently.

·Backend: NestJS on Fastify, Kysely for data access, PostgreSQL 18

·Queues and deadlines: graphile-worker on the same PostgreSQL

·Team configuration: JSON Schema validated with Ajv

·Web: React, Vite, React Router, TanStack Query, HeroUI v3, Tailwind CSS v4, i18next

·Models: the Anthropic and OpenAI SDKs, the latter also serving DeepSeek through its compatible API

·Layered tests with Vitest, from module boundaries up to the real processes with a simulated model provider

## In production

It runs in Docker containers on a server in the European Union. CI builds the images, tagged with the commit SHA, and every commit on main goes to production on its own: from CI the server accepts one thing only, deploying a commit of main, always with a database backup before the migrations. The database lives on a LUKS2-encrypted volume, and the nightly backups leave the server already encrypted with age, bound for Cloudflare R2.

Formicaio is a personal project, conceived, designed and developed alone, and I am its first user. The project documents — discovery, estimate, domain model, architecture, implementation plan and test plan — were written by donumAI and approved by me stage by stage. The criterion I judge it by is written in the gate: four weeks of daily use, with adherence of at least 80%. Everything else is intention.

// stack

[“nestjs”, “postgres”, “react”, “llm”, “fastify”, “kysely”, “graphile-worker”, “vite”, “heroui”, “tailwind”, “typescript”, “pwa”, “json-schema”, “docker”, ]