Systems & Information Architecture · Case Study

Case Study — A self-documenting, self-maintaining personal operating system

What: an information-architecture + automation system that organizes a multi-venture operator's entire digital life — and keeps itself from decaying. Role: designer & builder (with Claude Code) · Where it lives: the Mac itself — ~/Documents, ~/Library/LaunchAgents, ~/Documents/System Health, documented in 08_Systems-and-Information-Architecture/Infrastructure-Docs/ Prepared 2026-07-12

Status: live and running. The maintenance agent last executed 2026-07-12 09:31; six venture symlinks resolve; the audit log is ~500 KB. This is a working system, not a proposal — the numbers and artifacts below are read from the machine.

1. Summary

One person runs seven ventures (real estate, VC, AI, a book, coaching, a SaaS, a technical portfolio). Their files, by default, scatter across Documents, Desktop, Downloads, iCloud, and code repos until nothing is findable and no backup is trustworthy. This project is the operating system that fixes that — a coherent architecture (where every file goes and why), a single-source-of-truth venture pattern, a launchd automation loop that audits the system weekly, and a live, self-generated status report — the whole thing documented as versioned markdown so it can be understood, extended, and handed down.

It is the meta-skill made concrete: not a feature, but a system for keeping complexity navigable and self-sustaining. The design is deliberately boring in the best way — plain files, Bash, launchd, and markdown, no proprietary tooling — so it is fully portable and fully owned.

2. Problem

Entropy. A single operator generates documents faster than they can file them. Landing zones (Desktop, Downloads) fill; the "real" location of anything becomes ambiguous.
Trust. With no reliable backup discipline, moving a file to the wrong tier silently removes it from cloud sync.
Silent decay. Even a good structure rots if nothing watches it. Organization is not a one-time event; it needs a heartbeat.
Filename lies. Files are routinely mis-named (a "1165" folder holding 1144 leases; MBA case studies named like real deals). You cannot organize by filename alone.

3. Design goals

Five operating principles, enforced throughout:

Single source of truth — exactly one canonical folder per venture/topic; never duplicates.
Backed up by default — canonical data lives in iCloud (auto-synced); local-only paths are the flagged exception.
Content over filename — route files by what they are (verified by reading), not what they're named.
Reversible & logged — moves go to Trash, never rm; every operation is appended to an audit log.
Self-maintaining & observable — a scheduled job audits the system and reports its own state.

4. Architecture — storage tiers

Files live in one of four physical tiers, and the tier determines whether they're backed up:

Path	Tier	iCloud-backed?	Role
`~/Documents`, `~/Desktop`	Active	✅ (Desktop & Documents sync ON)	Entity/project working system
`iCloud Drive/Aer West`	Active	✅	Top-level venture operating system
`~/Archive`	Cold	❌ local	Category-based reference/cold storage
`~/Projects`, `~/PartnerOS`	Code	❌ local	Git repos / code workspaces (path-pinned)
`~/Media`	Media	❌ local	Photos / Screenshots / Videos

The load-bearing fact: because macOS Desktop & Documents Folders iCloud sync is ON, iCloud Drive/Documents is ~/Documents. Anything filed there is auto-backed-up; moving it to ~/Archive/~/Projects/~/Media removes it from that backup. Knowing this is the difference between a safe system and silent data loss.

Two organizing systems, one rule: - ~/Documents — entity system: one folder per company/venture/topic. - ~/Archive — category system: type-first (PDFs/, Word Docs/), then topic. - The rule: working on it → Documents; done/reference → Archive. ~/Downloads is a landing zone only.

5. The venture pattern (single source of truth + home-root access)

Every venture is one canonical iCloud-backed folder + a home-root symlink — never physical duplicates. Editing through the symlink edits the canonical file; no drift, always backed up. Live on the machine right now:

~/Asearis                    -> ~/Documents/Asearis
~/Lightside                  -> ~/Documents/Lightside
~/LightBear AI               -> ~/Documents/LightBear
~/The First Spark            -> ~/Documents/The First Spark
~/Service                    -> ~/Documents/Service        (basketball coaching)
~/Technical Skill Development -> ~/Documents/Technical Skill Development
~/Aer West Real Estate       -> iCloud Drive/Aer West
~/PartnerOS                  =  real local code workspace (path-pinned exception)

Onboarding a new venture is a documented copy-paste: make the canonical folder, symlink it, done.

6. Operating systems (numbered run-books)

Ventures that outgrow a folder graduate to a numbered operating system — a taxonomy + SOPs + an inbox. Aer West is the reference implementation: 00_Company-Administration … 15_Brand-and-Marketing, 02_Properties/{1144,1165} with 20 sub-areas each, 90_Inbox-To-File, 98_Archive, 99_System-Administration. The pattern is captured as a reusable template so any venture can be instantiated the same way.

7. Automation layer — the heartbeat

A launchd agent runs a maintenance script every Sunday 09:00:

<key>StartCalendarInterval</key>
<dict><key>Weekday</key><integer>0</integer><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>

The script (weekly-maintenance.sh, Bash) is report-only — it never deletes. Each run it:

audits the landing zones (Desktop / home / Downloads) for loose files and lists exactly what needs sorting,
counts the files in every venture,
checks free disk space and reminds about backup,
regenerates a live System-Status.md snapshot, and
appends a heartbeat line to maintenance-log.txt.

The design choice that matters: report-only by default. Automation that silently moves things is how you lose trust (and files). This one surfaces what needs attention; any destructive action stays a deliberate, logged, human-reviewed step. (The docs note the optional upgrade path: schedule a Claude Code agent for intelligent content-based filing when you want it to sort, not just flag.)

8. Observability

The system watches itself and reports in three artifacts:

System-Status.md — a machine-generated snapshot. Today's real output:

Landing zones → Desktop 0 · Home 2 · Downloads 1 (⚠ Downloads/README - archive moved.txt) Disk → 141Gi free Ventures → Aer West 403 · Asearis 65 · Lightside 15 · LightBear 29 The First Spark 22 · Basketball 150

maintenance-log.txt — an append-only heartbeat (2026-07-12 09:31 | desk=0 home=2 downloads=1 free=141Gi), so you can see the system has been running.
Organization-Log-YYYY-MM-DD.txt — the audit trail of every move (MOVED: / TRASHED: / RENAMED:). ~500 KB and counting — the reversibility guarantee made legible.
Operator Command Center — a hand-built HTML dashboard giving a single-pane view of all ventures + health.

9. Engineering patterns & principles

Reversibility as a hard rule — Trash, never rm; dedup by content hash (md5), not filename; dry-run then log. Nothing is unrecoverable.
Content over filename — real subject verified with pdftotext/textutil before filing, because filenames repeatedly mislead.
Report-only automation — the scheduled job surfaces, humans (or a deliberately-invoked agent) dispose. Trust is the feature.
Docs-as-code — the entire system is documented in versioned markdown (an 8-file infrastructure set), with an onboarding guide and an iteration workflow. The system explains itself.
macOS-internals literacy — the design accounts for the iCloud file-provider (Desktop/Documents sync), TCC protection (why the script can't read ~/.Trash without Full Disk Access), and FileVault. It works with the OS, not against it.
Portability by construction — plain files + Bash + launchd + markdown. No lock-in; fully inspectable; fully yours.

10. Outcomes & what it demonstrates

A real, running system — a launchd heartbeat (last run 2026-07-12 09:31), six live venture symlinks, a self-generating status report, and a ~500 KB audit trail.
At real scale — 1,200+ files organized via content-based classification and md5 dedup, fully logged — an information-retrieval + data-hygiene exercise, not a tidy demo.
Coherent by design — five principles applied consistently across storage tiers, the venture pattern, the automation, and the docs.
The meta-skill, shown — most engineers don't build a documented, self-maintaining operating system for their own operations. This is systems design, information architecture, automation, and docs-as-code, executed end-to-end.

Net: evidence of an operator who designs systems that stay organized — the rare combination of architectural thinking and the operational discipline to make it durable.

11. What's next

Render an architecture diagram of the tiers + data flow (make the design legible at a glance).
Add guarded, logged auto-filing (the Claude Code agent upgrade) for content-based routing, not just flagging.
Extend the maintenance audit (Trash size, tmutil latestbackup) once Full Disk Access is granted.
Stand up the offline SSD/Time Machine backup to complete the "backed up by default" guarantee for the local tiers.

Appendix · Artifact & code map (real paths)

Artifact	Role
`~/Library/LaunchAgents/com.abhiprakash.weekly-maintenance.plist`	Scheduler — Sundays 09:00
`~/Documents/System Health/weekly-maintenance.sh`	Report-only audit + status generator (Bash)
`~/Documents/System Health/System-Status.md`	Live machine-generated snapshot
`~/Documents/System Health/maintenance-log.txt`	Append-only heartbeat
`~/Organization-Log-YYYY-MM-DD.txt`	Move-by-move audit trail (~500 KB)
`~/{Venture}` symlinks → `~/Documents/{Venture}`	Single-source-of-truth venture pattern
`08_.../Infrastructure-Docs/` (8 markdown files)	The authoritative, versioned documentation set
Operator Command Center (HTML dashboard)	Single-pane venture + health view

Stack: information architecture · taxonomy design · Bash · launchd · macOS internals (iCloud file-provider, TCC, FileVault) · md5/pdftotext/textutil · docs-as-code (markdown + git).

Grounded entirely in the live system and its infrastructure docs as read on 2026-07-12 (the launchd run time, symlink map, status numbers, and log size are read from the machine). Nothing here is aspirational; the "What's next" section names what isn't done yet.