Home

reportmate-api

reportmate-api is the server side of ReportMate: a FastAPI application that accepts telemetry from the macOS and Windows agents, stores each collection module as JSONB in PostgreSQL, and serves it back over a versioned REST API. It is the only component that talks to the database.

Everything ships as one container image. The same image runs on a laptop, on Azure Container Apps, or on ECS — the only required configuration is a database URL and a credential.

Where it sits

macOS agent ──┐
              ├── POST /api/v1/events ──> reportmate-api ──> PostgreSQL
Windows agent ┘                               ▲
                                              │
                          dashboard, CLI, MCP server (GET /api/v1/...)

Agents post a full collection payload on each check-in. The API upserts the device row, writes one JSONB row per module, records events, and accumulates application usage. Readers — the dashboard, the CLI, anything else holding a credential — query the same surface.

Contents

Page	What it covers
Getting-Started	Run the API against a local Postgres and make a first authenticated call
Architecture	Process layout, middleware stack, routers, caching, connection pool
API-Reference	Every route, its parameters, and its response shape
Configuration	Every environment variable, its default, and what it does
Data-Model	Tables, columns, indexes, and which component owns each one
Ingest-Pipeline	How a device payload becomes rows, and every way it can be rejected
Deployment	Container image, migrations on startup, probes, scaling notes
Development	Clone, run the tests, add a migration, regenerate the OpenAPI spec
Troubleshooting	Failure modes with their actual error text
Security	Credentials, scopes, OIDC, rate limiting, error masking

The rest of ReportMate

Repo	What it is	Wiki
reportmate-app-web	Next.js dashboard	wiki
reportmate-app-swift	Native macOS dashboard (SwiftUI)	wiki
reportmate-app-csharp	Native Windows dashboard	wiki
reportmate-client-win	Windows agent (C# / .NET), managedreportsrunner	wiki
reportmate-client-mac	macOS agent	wiki
reportmate-cli	Admin CLI, reportmateutil	wiki
reportmate-mcp	MCP server exposing the fleet to AI agents	wiki
terraform-azurerm-reportmate	Azure deployment module	wiki
terraform-aws-reportmate	AWS deployment module	wiki
selfhosted-docker-reportmate	Docker Compose stack + Packer appliance	wiki
reportmate-website	Marketing site, reportmate.app	wiki