This page was generated based on a 100% coding agent's review. No human change was involved.

Squillify C4 architecture

Back to the notice

1. Scope

This page describes Squillify with the C4 model:

1. System context: the people and outside services around Squillify.
2. Containers: the applications and data services that run separately.
3. Components: the main parts inside the web service and the projection worker.
4. Code hotspots: the rules that protect security, billing, and availability.

The stores in the diagrams are separate jobs. They may sit with the same provider, but their access, retention, and integrity rules stay different.

2. Summary

Squillify is a multi-tenant platform. It offers deterministic, metered MicroSkills to AI agents over REST and the Model Context Protocol, and it gives people a tenant workspace and a separate operator workspace.

• Two web applications: one for the public site and tenants, one for operators.
• One Java service that runs as either the web runtime or a projection worker, never both in the same process.
• PostgreSQL keeps tenant records, access, entitlements, quotas, commercial records, invoices, billable usage, and the models used for reporting.
• A Redis-compatible store handles rate limits, concurrency, caches, and a fast quota path. PostgreSQL remains the record that can correct it.
• Kafka carries telemetry. It is not the billing record and it is not the invoice archive.
• Object storage has three jobs: temporary tenant files, telemetry archives, and signed invoice documents.
• Heavy document and media work runs in separate workers. Those calls are authenticated and have no silent local fallback.
• Clerk identifies people. Stripe handles payments. Operations metrics are collected separately from customer traffic.
• Support tickets, including image and PDF attachments and ticket email, are part of the platform. Public and automated ticket creation stay closed.
• Capability Sets add a bundle of skills on top of the skills granted directly to an API key.
• Formula and diagram rendering uses separate renderers. If a renderer is down, that render fails rather than guessing a result.

A successful billable response does not get ahead of the PostgreSQL billing record. Streams, caches, and archives can make the platform faster or more durable. They do not replace that record.

3. System context

4. Containers

The two process roles are separate deployments, even though they share one program:

• The web runtime serves APIs. The projection worker only updates reporting models.
• The projection worker does not accept Kafka traffic and does not serve customer routes.
• Telemetry is accepted by the web runtime, stored durably, and then projected.
• The telemetry archive is also in the web runtime, with its own consumer and object store.
• An invoice is saved in the database together with a task to archive it. The file is written afterward and can be retried without undoing the invoice.

5. Inside the web runtime

The web runtime is easier to read as several contracts than as one diagram.

Who is allowed in

Each kind of caller uses its own door. A person's login is not an API key. An API key is not an operator login. A payment notice is accepted without a login, and it is still signature-checked.

Running a skill

Agents get three stable operations: search, read a contract, and execute. The catalog can grow without turning every skill into a separate tool. Search, contract, and execution use the same access decision, including skills inherited from a Capability Set.

For a billable call the order is fixed: reserve quota, run the skill, save the usage record, settle the quota, then report success. If the usage record cannot be confirmed, the reservation is released and the caller is asked to retry.

Limits

Plan limits live in PostgreSQL. The fast path can answer from the Redis-compatible store when that path is healthy. If it is not, the database path remains. Pressure on the service can also shed load without treating that as a billing event.

Usage and reporting

The usage ledger is the billing record. Reporting models are built afterward. They do not replace the ledger.

Telemetry archive

A record that cannot be archived is kept as a failure and then acknowledged. If the object or its index cannot be saved, the batch is retried. The object store alone is not the index.

Invoices

Invoice files are not taken from the telemetry stream. They follow the invoice record. If the file store is unavailable, the invoice remains issued and the file is retried. A conflicting file is quarantined rather than overwritten. This archive is switched on only with its own document store.

Files

Temporary files, telemetry archives, and invoice documents do not share one retention rule. They stay separate jobs even when an environment places more than one of them with the same storage provider.

Heavy workers

Parsers, codecs, and office engines that need a lot of memory or native code do not run inside the web service. Each family is its own service, with its own workspace, and it is reached only through Squillify. The platform decides which published build is allowed to run. The worker does not share the API process disk, and it cannot see another tenant's files except the bytes Squillify sends for that one job.

The families, taken from the skills catalog, are:

Formula rendering and diagram rendering sit beside this list, not inside it. They are lighter HTTP renderers. If one of them is down, that render fails rather than being invented locally.

Every worker of this kind follows the same shape:

• A dedicated service and a short-lived workspace that is cleaned up after each job.
• A pinned build and a signed identity. Rollout and rollback select those exact builds, not a floating name.
• Explicit limits for CPU, memory, concurrent jobs, queue size, deadline, and how many bytes the workspace may hold.
• It runs as an unprivileged user, with a read-only root disk, no extra operating-system privileges, and no access to the host disk.
• It has no outbound network by default. Any exception is a named destination list and a distinct caller identity.
• The temporary workspace is bounded, emptied at startup, emptied after each job, and swept if a job is abandoned.
• The connection is mutually authenticated. The worker's network name must match the expected identity exactly. Each request is also bound to its contents and protected against replay, even on a private network.
• A readiness check reports only whether the worker has capacity. An identity check returns the attested build. Neither check returns file contents, secrets, or tenant data.

The platform keeps a declaration for each worker. A call is refused unless every identity field matches:

If any of those fields do not match, the worker is unavailable. Squillify does not quietly run the same job inside the web service instead.

While a job runs, the platform records how many jobs are active, how deep the queue is, how often work is rejected or times out, how long it takes, whether the circuit is open, restarts, workspace size, output size, and failed identity checks. Alerts cover a worker that stays saturated, restarts in a loop, presents the wrong identity, times out too often, fails to clean up, or loses readiness.

Logs name the worker, the request, a tenant pseudonym, the operation, the status, the duration, and the byte counts. They do not include the file contents, file names, paths, credentials, the raw tenant identifier, or the worker's own error body.

A new build is activated only after its identity and readiness have been checked, and first for a limited set of tenants. Widening that set is a separate step. Rolling back restores the previous approved build and its signed description. The engine inventory is recorded for every build that is promoted.

Errors and operations

Every response can carry a request id. Public errors name the problem and whether a retry makes sense. They do not include stack traces, queries, file paths, secrets, or another tenant's data. Health information is public. Detailed metrics require the operations token.

6. Projection worker

This process does not include the web runtime's APIs, login, skill execution, or telemetry intake. That keeps reporting work from opening those doors.

7. Rules that must hold

8. Decisions

9. Where each kind of data lives