System architecture

Genie OS knowledge loop

Canonical documents live in Git. The Go server applies identity and resource permissions. Workers process durable jobs and return every result through the same governed API.

Derived from SPEC.md
Document, permission, and agent paths
1

Create a new document

Fast path for a strictly new ordinary document, task, or decision.

No overwrite
Caller submitsContent, owner, metadata, expected Git parent, and idempotency key.
→
Authorize and validateCheck current identity, create capability, schema, ACL, path, and stable ID.
→
Prove it is newReject an existing path or ID, delete, move, skill, policy, or learning output.
→
Commit to GitChange service creates one validated commit on the approved ref.
→
Project and indexVerified receipt updates SQL, then optional embeddings process the committed version.
2

Update or govern existing knowledge

Existing documents, deletes, skills, policies, and learning output use review.

Merge is approval
Caller proposesAn agent or user submits a structured or textual change with provenance.
→
Authorize proposalCheck propose authority, document ACL, affected projects, and policy class.
→
Create branch and PRPartition by compatible ACL and project-owner review audience when needed.
→
Exact-head reviewEligible Owners or delegated reviewers inspect provenance, diff, and checks.
→
MergeRe-authorize, verify the exact head, merge, receipt, project, and index.
Reject or reviseRetain the decision; a correction creates a new proposal head.
3

Agent loop and scheduled job

The same loop works for Cloudflare Agents SDK, Codex SDK, or another conforming runtime.

Lease and checkpoint
TriggerA cron, ingestion timer, realtime event, manual request, or insert hook creates work.
→
Lease runWorker gets run identity, fenced lease, budgets, and a short-lived user-scoped capability.
→
Read through APIEvery search and fetch applies current document permissions and returns minimum context.
→
Process and checkpointCall the model runtime, heartbeat, save progress, and use idempotency for side effects.
→
Return through APICreate a document, propose an update, add an approval, or add a user queue item.
↺
Continue or resumeThe server records status and can resume the same conversation and run identity.

Every read is filtered

Discovery, metadata, content, search, app data, and agent context use the same current policy.

  • Ownership and explicit grants
  • Participants and project or channel membership
  • Explicit Git denial takes precedence

Every write is attributed

The server records the human or service principal and checks both route capability and resource authority.

  • API keys inherit current user access
  • Apps intersect app grants with user access
  • Workers receive short-lived run capabilities

SQL cannot create truth

Only a verified accepted Git commit can update projected document metadata.

  • Operational grants take effect immediately
  • Content updates still follow Git policy
  • Projector credentials are separate
System reference

How the parts fit together

Git holds company knowledge. SQL makes that knowledge fast to find and protects operational workflows. Embeddings add optional semantic retrieval. Every access path still passes through the Go server.

Canonical knowledge

Documents and data types

A document is a Git-tracked file with a stable ID and validated metadata. Its path may change without changing its identity. Text normally uses Markdown with frontmatter. Connected providers map their records into the canonical types instead of creating provider-specific types. A transcript is always a meeting.

People and companiesorganization
contact
Work and knowledgeproject · task · decision
workflow · skill
Communication and timemessage · meeting
calendar_event
System documentsfile · object_manifest
access_policy · tombstone
Required identityID, type, title, owner, schema version, and creation and update times.
Access metadataVisibility or ACL reference, participants, project, channel, and access-scope tags.
Source and provenanceSource provider, source object ID, transformation history, and accepted Git commit.
RelationshipsRelated document IDs, object IDs, and stable wiki links that produce permission-safe backlinks.
Source of truth

Git company brain

Git stores every canonical document version, policy, skill, provenance record, and tombstone. A strictly new ordinary document can use a validated direct commit. Existing-document changes, deletions, policies, skills, and learning output use a pull request. Merge is the approval event.

Validated file→Git commit→Accepted receipt
Fast lookup

Projection SQL

This plane contains current document records, versions, paths, types, aliases, wiki links, relationships, provenance, tombstones, and projected access policy. Only the commit projector can write it. The Go server uses a read-only identity for filters, relationships, authorization, and lexical retrieval.

Receipt→Verify Git→Atomic projection
Mutable workflow state

Operational SQL

This plane changes without a document merge. It stores principals, roles, sessions, API keys, immediate resource grants, encrypted secrets, sync cursors, leases, cron jobs, agent runs, checkpoints, proposals, approval decisions, exception queues, action ledgers, and the audit outbox. Its writer cannot change projected documents.

Portable adaptersPostgreSQL, MySQL, and SQLite use the same logical contracts.
Separate authorityOperations writes and projection writes always use different credentials.
Optional derived index

Embeddings and vector search

Embeddings contain chunks from accepted document versions. Each chunk carries document ID, commit, type, date, source, project, ACL scope, language, and model version. The index is disposable and can be rebuilt from Git. Permission filters or an authorized candidate list apply before results leave the trusted boundary.

Disabled by defaultLexical search and every non-semantic workflow continue without vectors.
Provider-neutralA connection string and pinned provider API specification support Pinecone, pgvector, local SQLite vectors, or another certified adapter.
Large content

Object storage

Images, video, audio, and other large binaries do not enter ordinary Git history. Git stores a small object manifest with an immutable content-addressed object ID. Authorized reads use the API and may receive a short-lived signed URL.

Policy enforcement

Go server

The Go server is the only supported user, agent, and app access layer. It authenticates the caller, checks route capabilities, evaluates resource access, filters retrieval, coordinates runs, serves the UI and API documentation, and creates correlated audit records. Agents never receive SQL or vector-store credentials.

Background execution

Schedulers, queues, and workers

Schedulers create due runs. Workers acquire fenced leases, use short-lived capabilities, heartbeat, checkpoint, and return outputs through the API. Ingestion workers make one source item per document and one commit per cycle. Learning and agent workers create proposals or user queue items. The commit projector updates SQL. The optional embedding worker updates vectors only after projection.

Timer, hook, or request→Durable job→Leased worker→Permissioned API loop→Commit, proposal, or queue item