Skip to content
osapi-ioPublic

About

Design docs for osapi-io. Written before the code, corrected when the code proves them wrong.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

specs

The design docs for osapi-io. We write them before the code, and correct them when the code shows an error.

license conventional commits docs driven built with just github commit activity

Doc-driven: the page is the design, then the description.

You design something when you write its page. Then you build it. Then you correct the page where the build showed an error. It is the same page all three times. Nothing changes from one form into another, because that change is where the design and the docs become different.

🚀 Usage

osapi-io makes a Linux host operate like an appliance. One binary and a config file give you a REST API, a CLI, a Go SDK and an embedded dashboard. They manage hostname, DNS, disk, memory, load, packages, services, users, sysctl, cron, certificates, containers, files and command execution. They do this on a fleet, not on one machine.

All of the design follows from one fact: osapi queues work for a host. It does not call the host. The controller writes a job and waits. An agent takes the job, and a provider does the work on the machine. These properties come from that one decision:

  • at-least-once delivery
  • the idempotency that each provider must have
  • two independent timeouts
  • a result for each host
components/     one page per repository, plus a page per subject
ARCHITECTURE.md how they fit together, and what breaks what
CONSTITUTION.md the rules every repository follows

Read osapi first. Its subject pages are below it. Four of the other five repositories give data to it or use it.

📝 Doc-driven development

Design something when you write its page. Build it. Correct the page where the build showed an error. It is the same page all three times. Nothing changes from one form into another, because that change is where the design and the docs become different.

Thus a change here is one of four things:

You are Change
Designing something new A new page under its component
Changing how something behaves The page that already covers it
Agreeing something between repositories ARCHITECTURE.md
Binding every repository to a rule CONSTITUTION.md

CONTRIBUTING.md has the test that selects one, and tells what a page looks like.

What keeps it honest

A reader. Give a person only the page. Ask the question that the page says it answers. Fix what the person could not find. This test found these errors:

  • seven permissions where a page said one
  • thirteen struct fields where a page said fourteen
  • a bucket TTL that a page described in the opposite direction

🗂️ The design docs

Repository Is
osapi The API and the agent that manage a host
osapi-orchestrator A declarative layer over osapi's SDK
nats-client A wrapper over the NATS client
nats-server A NATS server embedded in its consumer
gohai A system fact collection library, standalone
osapi-justfiles Shared just recipes

These four facts surprise people most often. Each one has a page:

🤖 Skills

The skills here answer questions about all of the repositories. They also have the operational knowledge for work in them.

No skill lists what it describes. org-status gets the repository list from GitHub each time it runs. add-a-domain finds its reference domain in the codebase. document reads the component pages that exist, not a table of them. An inventory in a skill is correct on the day that somebody writes it. It is incorrect after the next change, and nothing shows that change.

Skill Answers
document Where a design goes, what the page looks like, and if a page already covers it
org-status Open pull requests, Dependabot updates, security alerts, CI status, and the merge queue across osapi-io
add-a-domain How to add an osapi domain. A pointer: the osapi binary has the skill (osapi skill get --name add-a-domain)
release If a repository needs a tag, which number it gets, and if the tag will publish
work-an-issue How to take an issue to a merged pull request: if the problem still occurs, its size, the fix and its test
ste-100 How to write and check pages in ASD-STE100 Simplified Technical English, the sentence rules that each page here obeys

Each skill uses the Agent Skills format. A short SKILL.md sends the agent to the correct reference file. An agent reads a reference file only when the question needs it.

The skills are in .claude/skills/. .agents/skills is a link to that directory, so each coding agent finds the same copy. AGENTS.md is the instructions file for all agents. CLAUDE.md points to it.

🤝 Contributing

Refer to the Contributing guide for the prerequisites, the test that tells where a change goes, what a page looks like, and the PR workflow.

📄 License

The MIT License.

About

Design docs for osapi-io. Written before the code, corrected when the code proves them wrong.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages