5.9.1 Introduction

grant is the system responsible for MooGrant: the Italian public funding calls shown to livestock farms, every fact cited from its source document; the register of sources and the research collections staff register; the extraction batches that read the documents, verify every quote and store immutable revisions; the publication of the catalogue; and the farmer's side: the research, the farm, the results, the documents a farmer uploads and the facts read from them, checked against each call's requirements. It belongs to the Funding domain of the platform. Every interface it offers follows Choosing an Interface. Its requirements live in the design folder [1] moonitoring-grants (written on 2026-10-30 from the MVP, D12).

Proposal for review

The contracts of this system are a proposal, not confirmed design: endpoints, events and calls were written from the refined requirements, the data model and the flows, and wait for review. What needs a decision is collected in Open Decisions.

5.9.1.1 Host Names

Environment	Host
Prod	grant.moonitoring.com
Stage	stage-grant.moonitoring.com, behind IAP

The names follow the host name rule; on a developer's computer each service answers on a local port (Running Locally). Each domain below is a path on these hosts, followed by its version: https://grant.moonitoring.com/<domain>/v1.

5.9.1.2 Domains

Each domain of grant is one API, with its own contract and its own version.

• 5.9.2.1 Funding Calls

  Funding calls for livestock farms, every fact cited from its source document (req 200 to 209). /calls/v1

• 5.9.2.2 Research

  The farmer's side of MooGrant (req 210 to 214): the research that owns everything a farmer leaves with us, the farm as the journey describes it, the results that match its comune and purposes, the count that follows the journey, and what the farmer did with each call. /research/v1

• 5.9.2.3 Farmer Documents

  The documents a farmer uploads from a call's check (fascicolo aziendale, visura camerale, registro BDN, report ClassyFarm), private to the research and read by a worker into typed facts with their citations; the farmer sees every fact, can dispute one, and the requirements of a call are evaluated against the facts (req 215 to 218). /documents/v1

5.9.1.3 How It Is Used

Public reader

1. A visitor opens bandi.moonitoring.com and browses the published funding catalogue through the Calls domain.
2. The site shows facts cited from the source documents so the reader can understand why a call appears.

Farmer research

1. A farmer describes the farm, leaves a phone number, and receives a private credential lasting 90 days from the last visit, or signs in through Access.
2. The Research domain matches the farm's comune and purposes to published calls.
3. The farmer sees the matching calls and the requirements that still need evidence; the product does not issue a final funding verdict.

Document extraction

1. From a call check, the farmer uploads documents directly to the research's private bucket.
2. A worker sends the document to AI Gateway for extraction; personal data is sent only to Vertex AI in the EU.
3. Grant stores typed facts with citations and evaluates requirements against them; only a definitely failed requirement excludes a call.

Staff publication

1. Staff use the Console to register source documents and research collections.
2. Staff launch or resume extraction batches, while Grant journals model calls so work is not paid twice.
3. Staff publish, hold, or restore catalogue revisions; nothing starts work without an explicit action.

flowchart LR reader{{Public reader}} -->|REST catalogue| grant[Grant API] farmer{{Farmer}} -->|REST documents and checks| grant console{{Console}} -->|REST publishing| grant grant -->|gRPC extraction| gateway[AI Gateway] grant -->|gRPC access and usage| platform[Access / Farm]

• Called by: Console (REST); Organization Dashboard (REST); Public readers (REST); access (gRPC CatalogService); farm (gRPC CatalogService); moochat (gRPC CatalogService).
• Calls: access (gRPC OrganizationsService); ai-gateway (gRPC BatchesService, gRPC CompletionsService); farm (gRPC EntitlementsService).
• Publishes events consumed by: moochat (3 event types).
• Consumes events of: access (1 entry), ai-gateway (1 entry), farm (2 entries).
• Reads no other system's database: everything above goes through a contract on this page or an event.

5.9.1.4 Synchronous Calls Between Systems

None served. It calls CompletionsService of ai-gateway and OrganizationsService.StreamSnapshot of access.

5.9.1.5 Events

Events are facts in the past tense, published through the outbox and delivered at least once on the topic grant.events.v1; the envelope and the guarantees are in common/v1/events.yaml. Events marked outside reach the Pub/Sub subscriptions an Organization registers in Webhooks, pushed to its HTTPS endpoint or pulled by its own service account.

Publishes (contract: events/v1/asyncapi.yaml):

Event	Published when	Consumers	Outside
funding_call.published.v1	A call was published, held, restored or reverted: the public catalogue changed and its version was bumped.	moochat	yes
farmer_document.uploaded.v1	A document was uploaded and finalized; a worker execution is dispatched for it. Internal: one message per document.	none yet	no
farmer_document.read.v1	A worker finished reading a document: ready, partial or failed; its facts are usable at once and the profile revision moved.	moochat	yes
grant_check.changed.v1	The check of a call against a farm's facts changed its verdict after a new document, a dispute or a rule version.	moochat	yes

Consumes:

Event	From	Why
organization.*.v1, membership.*.v1	access	Keeps its copy of who may act for an Organization.
entitlement.*.v1, feature_usage.limit_reached.v1	farm	Gates and meters eligibility checks.
provider.degraded.v1	ai-gateway	Pauses extraction batches.
erasure_request.executed.v1	farm	Deletes the farm's documents and checks.