Ryan Schultz
299e38f696
Convert bold titles to ### headers in ARCHITECTURE.md. Wire ADRs and site files to specific section anchors. Add AI agent guidance in README to treat loose "see X" references as technical debt and replace them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
50 lines
1.8 KiB
Markdown
50 lines
1.8 KiB
Markdown
# ADR 001 — Python + git-tracked JSON as the foundation
|
|
|
|
**Date:** 2026-05-10
|
|
**Status:** Accepted
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
We needed a starting tech stack for a participation signal system aimed at the OSArch
|
|
community. The system should be transparent, forkable, and approachable to contributors
|
|
who are not professional software engineers.
|
|
|
|
---
|
|
|
|
## Options considered
|
|
|
|
| Option | Notes |
|
|
|---|---|
|
|
| Python + JSON files | Simple, readable, no infrastructure needed |
|
|
| Python + SQLite | More structured, still local, but opaque binary format |
|
|
| Python + PostgreSQL | Full relational DB, requires a running server |
|
|
| JavaScript/Node | Less familiar to OSArch/BIM ecosystem |
|
|
| CouchDB / distributed DB | Better eventual fit, too complex for day one |
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
**Python with git-tracked JSON files.**
|
|
|
|
Python is the native language of the OSArch/BIM ecosystem (IfcOpenShell, Bonsai, FreeCAD
|
|
macros). Using it lowers the barrier for community members to read, run, and contribute.
|
|
|
|
JSON files checked into git serve as the "database." This means:
|
|
- The entire history of participation data is version-controlled
|
|
- Anyone can fork the repo and fork the data with it
|
|
- No server or database installation required to run the system
|
|
- Changes to data are visible as diffs, not opaque DB mutations
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- Scaling to thousands of users will eventually require a real database
|
|
- Concurrent writes are not safe (not a concern at this stage)
|
|
- Data must be hand-edited or script-generated — no admin UI yet
|
|
- The distributed database goal is achieved through git forking, not replication
|
|
(see [Git as the distributed database](../ARCHITECTURE.md#git-as-the-distributed-database)
|
|
and [future distributed DB directions](../ARCHITECTURE.md#distributed-database--tamper-evident-records))
|