Architecture
How Phiacta is designed to be a permanent, general-purpose knowledge platform.
Git for Content, Postgres for Facts
Every entry on Phiacta is a git repository. Version history, supporting files, edit proposals, and issues all live in that repository. What lives in the database are the facts that need to be queryable: references between entries, tags, and identity.
The database stores only what users directly provide—no derived or computed values. Search indexes and knowledge maps are computed at query time by separate analysis modules and are never written back into the ground truth store.
System Architecture
Extensions & Views (pluggable, never stored in core)
identity, refs, search
content, history, files
Core Entities
The core schema is deliberately minimal. The architecture separates entries (core), extensions (tags, references, search, etc.), and tools (search endpoints, graph traversal).
Entity Relationships
The central entity — everything connects here
References
Typed connections between any two entries
Edit Proposals
Content change requests on an entry's repository
Users
Humans, AI models, organizations, or automated pipelines
Tags
Extension: categorize entries with freeform labels
Files
Supporting materials stored in the entry's git repo
History
Git commit log for every entry
- Entries— Atomic assertions, each backed by a git repository. Content is versioned via git commits. Edit proposals (branches + PRs) and issues live in the same repository. Supporting materials—data, code, proofs—are committed alongside the entry content.
- References— Typed, directed connections between entries. Reference types include evidence, rebuttal, citation, derivation, supersession, and more.
- Users— Any entity that contributes knowledge: humans, AI models, organizations, or automated pipelines.
- Tags— An extension that allows freeform categorization of entries. Tags are stored separately from the entry core schema.
Entries as Git Repositories
Each entry is a git repository hosted internally on Forgejo. Users never interact with Forgejo directly—they use the Phiacta API or website, which proxy all git operations.
Git concepts are surfaced to users with plain-language names:
| Under the hood | What you see |
|---|---|
| Repository | Entry |
| Commit | Update / version |
| Branch + pull request | Edit proposal |
| Issue | Issue |
| Merge | Accept edit |
| Close PR | Reject edit |
| Fork | Derive |
Entry repository structure
{entry_uuid}/
├── .phiacta/
│ ├── entry.yaml # identity only (entry_id, schema_version, author, created_at)
│ └── content.md # entry content (or .tex, .txt)
└── (user files) # everything outside .phiacta/ is user-ownedTitle, summary, and type are DB-only. They are stored in extension tables and are not present in entry.yaml or any git file. They are set during entry creation and updated directly in the database.
Extensions & Views
The core schema is interpretation-free. Higher-level meaning lives in extensions—composable modules that read core data and expose their own data and API endpoints.
Metadata Extension
Stores entry titles and summaries. These are auto-composed into every entry response, so they appear as native fields even though they live in a separate table.
References Extension
Typed, directed connections between entries. Reference types include evidence, rebuttal, citation, derivation, supersession, and more. DB-only — not git-derived.
Tags Extension
Freeform tagging of entries. Tags are stored in a separate table and exposed through the API. Supports filtering entries by tag.
Search View
Full-text search across entry titles and content using PostgreSQL tsvector indexing. Precomputed and versioned — can be rebuilt at any time.
Why This Design
- Git-backed permanence— Every version of every entry is preserved forever. Nothing is deleted. Citations always resolve.
- Proof over assertion— Supporting materials (data, code, formal proofs) are first-class content in every entry repository.
- API first— Every feature on the website is accessible through the API. The website is a thin client. The API is the platform.
- Ground truth only— The database stores only what users provide. Derived values are computed on demand and never contaminate the source data.
- Record, don’t resolve— Contradictory entries coexist. The system records what has been asserted and by whom. Resolution is left to the community.
- Accessible to everyone— Git concepts are surfaced with plain-language names. No technical knowledge of git is required to use Phiacta.