Ryan Schultz 299e38f696 docs: cross-link docs with anchors + guide AI agents to maintain them

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>

2026-05-11 13:01:29 -05:00

1.8 KiB

Raw Permalink Blame History

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 and future distributed DB directions)

1.8 KiB Raw Permalink Blame History