# How it works

SuperCI has three parts. All of them run in accounts you control; there is no SuperCI service in between.

## The dashboard

A program on your computer, started with `npx @superci/cli dashboard`. It is where you set things up and look at jobs. It answers only on your own computer. It keeps SuperCI's own sign-ins to your clouds in `~/.superci`, so it opens signed in, and it reads no other tool's credentials; `superci logout` removes them. It keeps no settings: what it shows, it reads from your cloud and your control plane each time.

## The control plane

A small program in your own cloud account, deployed by the dashboard:

| Where | What it is |
|---|---|
| Cloudflare | A Worker with a Durable Object for its state |
| AWS | A Lambda function with a function URL, a DynamoDB table and a two-minute schedule |
| Modal | An app with a web endpoint, its state in Modal Dicts |

It does three things:

1. It receives job events from GitHub and GitLab, and checks they are really from them.
2. It starts a machine for each job, in the provider your order picks.
3. It cleans up: machines whose job never came, and machines past the time limit.

It holds the settings you make in the dashboard (the order, limits, connections) as its own secrets. The dashboard updates it with one click when a new version is out.

## A machine per job

Every job gets a machine of its own, of the size its label asks for. The machine registers as a runner for exactly that job, runs it, and is ended when the job ends. Nothing is shared between jobs, and nothing is kept running in between.

A job may run for up to six hours, as on GitHub's own runners. You can set another length (Settings → Limits → Longest job): up to five days on AWS, a day on Modal; Cloudflare keeps a container six hours at most. A machine ends itself at that limit even if the control plane is unreachable, so none is left running.

## From a push to a finished job

1. You push. GitHub queues a job whose `runs-on` is `superci`.
2. GitHub tells your control plane about it.
3. The control plane goes down your list of providers and starts a machine at the first one that can run the job.
4. The machine starts GitHub's runner, registered for this one job.
5. The job runs. Its logs are on GitHub, as always.
6. The job ends, the machine is ended, and the dashboard shows what it cost.

A job cancelled before its machine took it has that machine ended at once.
