# kunalamin/mypka architecture

> Architecture diagram of the GitHub repository kunalamin/mypka, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunalamin/mypka
- Repository: https://github.com/kunalamin/mypka

## Overview

1. **What this repository is**
   - This is not an application with a server/runtime; it is a **local, file-based knowledge operating system**.
   - The architecture centers on **plain Markdown on disk** plus an external **LLM tool** (Claude Code, Codex CLI, Gemini CLI, Cursor, Obsidian chat plugin, etc.) that reads and writes the folder structure.

2. **Control plane: root-level orchestration**
   - The root `AGENTS.md` is the **global source of truth** for how the system behaves.
   - `ADAPTER-PROMPT.md` is the bootstrap prompt that an LLM tool uses to initialize the workspace and generate a tool-specific pointer file such as `CLAUDE.md` or `GEMINI.md`.
   - `VERSION`, `CHANGELOG.md`, `CONTRIBUTING.md`, `WAY-FORWARD.md`, and the license/notice files define the repo’s governance and lifecycle, not runtime behavior.

3. **Agent layer: the AI team**
   - `Team/` contains the specialist contracts, one folder per agent, each with its own `AGENTS.md`.
   - `Team/agent-index.md` acts as the routing table for the team.
   - The shipped specialists are:
     - **Larry**: orchestrator and librarian; all user interaction flows through him.
     - **Nolan**: talent acquisition / hiring workflow.
     - **Pax**: deep research and sourcing.
     - **Penn**: journal writing and filing.
   - The architectural boundary here is important: **Larry routes and synthesizes; specialists do the work**.

4. **Knowledge core: `PKM/`**
   - `PKM/` is the canonical knowledge store.
   - It is organized by domain slices such as:
     - `My Life/` for the personal operating model
     - `CRM/` for people and organizations
     - `Documents/` for important documents
     - `Journal/` for daily notes and chronological capture
     - `Images/` for dated media references
   - Notes are meant to connect via **wikilinks** rather than deep folder nesting, so the graph is in the links, not the directory tree.

5. **Personal knowledge model inside `My Life/`**
   - `PKM/My Life/` is the main personal framework and is explicitly split into five life concepts:
     - Goals
     - Habits
     - Topics
     - Projects
     - Key Elements
   - This is the repo’s most important semantic structure for personal organization; it is where long-lived life-management notes live.

6. **Capture boundary: `Team Inbox/`**
   - `Team Inbox/` is the ingestion point for raw, unstructured inputs.
   - Inputs like screenshots, voice memos, business cards, links, or rough thoughts land here first.
   - The intended flow is **Inbox → Penn/Larry processing → proper location in `PKM/`**.
   - This is the repository’s main “untrusted input” boundary.

7. **Working area: `Deliverables/`**
   - `Deliverables/` is the team’s transient work surface for research briefs, workups, and multi-file artifacts.
   - Pax places research here; Nolan places hiring workups here; Larry aggregates multi-specialist outputs here.
   - This folder separates **in-progress or client-facing outputs** from the canonical knowledge base in `PKM/`.

8. **Process layer: `Team Knowledge/`**
   - `Team Knowledge/` contains the playbooks that define how the team operates.
   - It is divided into:
     - `Guidelines/` for static conventions like naming rules
     - `SOPs/` for atomic procedures
     - `Workstreams/` for multi-step, multi-agent workflows
   - Examples in the repo include daily journaling and vault-to-SQLite migration, which show that the system supports both everyday routines and future scaling paths.

9. **Externalization and extension points**
   - `docs/extension-spec.md` defines how extensions are supposed to fit the scaffold.
   - `Extensions/` and `Extensions/INDEX.md` are the architectural slot for optional add-ons.
   - The README makes clear that some extensions are membership-only and not part of the open scaffold, so the repo is designed to be extensible without those components present.

10. **Assets and presentation layer**
   - `assets/` contains the visual and media assets used by the documentation and team avatars.
   - These files do not affect data flow, but they support the human-facing presentation of the agent system and onboarding docs.

11. **Primary data flow**
   - The dominant flow is:
     - user input enters through the LLM tool
     - Larry receives the request
     - Larry routes to the right specialist
     - the specialist writes to `Deliverables/`, `Team Knowledge/`, or `PKM/` depending on the task
     - Penn/Larry file or normalize information into canonical notes
   - The system is intentionally **read/write on the filesystem**, with the LLM acting as the process layer rather than a hidden backend.

12. **Scaling boundary: plain Markdown first, SQLite later**
   - The repo’s default architecture is **Markdown-first and tool-agnostic**.
   - A documented migration path exists to add SQLite as a lookup layer when the vault grows, but Markdown remains the source of truth.
   - This keeps the core architecture simple: **filesystem canonical, database optional**.

13. **What to draw in an architecture diagram**
   - Show a central local folder vault with four major zones:
     - **Control/agent contracts**: root `AGENTS.md`, `Team/`
     - **Canonical knowledge**: `PKM/`
     - **Processing/workspace**: `Deliverables/`, `Team Inbox/`
     - **Operating procedures**: `Team Knowledge/`
   - Outside the vault, show the **LLM client** as the runtime that interprets prompts and edits files.
   - The key boundaries are **input capture**, **agent routing**, **canonical storage**, and **ephemeral work products**.

Main entry points: [`PKM/INDEX.md`](https://github.com/kunalamin/mypka/blob/main/PKM/INDEX.md) (PKM), [`Team/agent-index.md`](https://github.com/kunalamin/mypka/blob/main/Team/agent-index.md) (Agent index), [`Team Knowledge/INDEX.md`](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Knowledge/INDEX.md) (Team Knowledge), [`AGENTS.md`](https://github.com/kunalamin/mypka/blob/main/AGENTS.md) (Global AGENTS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_control["Control plane"]
  node_node_llm_tool(("LLM client<br/>external runtime"))
  node_node_adapter_prompt["Adapter prompt<br/>bootstrap prompt<br/>[ADAPTER-PROMPT.md]"]
  node_node_root_agents["Global AGENTS<br/>control contract<br/>[AGENTS.md]"]
end

subgraph group_group_agents["Agent layer"]
  node_node_agent_index["Agent index<br/>routing table<br/>[agent-index.md]"]
  node_node_larry["Larry<br/>orchestrator<br/>[AGENTS.md]"]
  node_node_nolan["Nolan<br/>HR specialist<br/>[AGENTS.md]"]
  node_node_pax["Pax<br/>research specialist<br/>[AGENTS.md]"]
  node_node_penn["Penn<br/>journal specialist<br/>[AGENTS.md]"]
end

subgraph group_group_knowledge["Canonical knowledge"]
  node_node_pkm[("PKM<br/>knowledge vault<br/>[INDEX.md]")]
  node_node_my_life["My Life<br/>personal framework<br/>[README.md]"]
  node_node_crm["CRM<br/>people knowledge<br/>[INDEX.md]"]
  node_node_documents["Documents<br/>document vault<br/>[INDEX.md]"]
  node_node_journal["Journal<br/>chronological notes<br/>[INDEX.md]"]
  node_node_images["Images<br/>media index<br/>[INDEX.md]"]
end

subgraph group_group_workspace["Working areas"]
  node_node_team_inbox["Team Inbox<br/>capture inbox<br/>[README.md]"]
  node_node_deliverables["Deliverables<br/>work surface<br/>[README.md]"]
end

subgraph group_group_process["Operating procedures"]
  node_node_team_knowledge["Team Knowledge<br/>playbooks<br/>[INDEX.md]"]
  node_node_guidelines["Guidelines<br/>standards<br/>[INDEX.md]"]
  node_node_sops["SOPs<br/>procedures<br/>[INDEX.md]"]
  node_node_workstreams["Workstreams<br/>workflows<br/>[INDEX.md]"]
end

subgraph group_group_docs["Docs and extensions"]
  node_node_extensions["Extensions<br/>extensibility slot<br/>[INDEX.md]"]
  node_node_ext_spec["Extension spec<br/>specification<br/>[extension-spec.md]"]
  node_node_assets["Assets<br/>media support"]
end

node_node_llm_tool -->|"bootstraps"| node_node_adapter_prompt
node_node_adapter_prompt -->|"loads"| node_node_root_agents
node_node_root_agents -->|"delegates"| node_node_agent_index
node_node_agent_index -->|"routes to"| node_node_larry
node_node_agent_index -->|"routes to"| node_node_nolan
node_node_agent_index -->|"routes to"| node_node_pax
node_node_agent_index -->|"routes to"| node_node_penn
node_node_larry -->|"ingests"| node_node_team_inbox
node_node_larry -->|"assembles"| node_node_deliverables
node_node_penn -->|"files into"| node_node_pkm
node_node_pax -->|"writes"| node_node_deliverables
node_node_nolan -->|"produces"| node_node_deliverables
node_node_team_inbox -->|"processed by"| node_node_penn
node_node_team_inbox -->|"triaged by"| node_node_larry
node_node_deliverables -->|"promoted to"| node_node_pkm
node_node_pkm -->|"contains"| node_node_my_life
node_node_pkm -->|"contains"| node_node_crm
node_node_pkm -->|"contains"| node_node_documents
node_node_pkm -->|"contains"| node_node_journal
node_node_pkm -->|"contains"| node_node_images
node_node_team_knowledge -->|"organizes"| node_node_guidelines
node_node_team_knowledge -->|"organizes"| node_node_sops
node_node_team_knowledge -->|"organizes"| node_node_workstreams
node_node_workstreams -->|"operates on"| node_node_pkm
node_node_ext_spec -->|"defines"| node_node_extensions
node_node_assets -.->|"supports"| node_node_root_agents
node_node_root_agents -.->|"references"| node_node_team_knowledge

click node_node_adapter_prompt "https://github.com/kunalamin/mypka/blob/main/ADAPTER-PROMPT.md"
click node_node_root_agents "https://github.com/kunalamin/mypka/blob/main/AGENTS.md"
click node_node_agent_index "https://github.com/kunalamin/mypka/blob/main/Team/agent-index.md"
click node_node_larry "https://github.com/kunalamin/mypka/blob/main/Team/Larry - Orchestrator/AGENTS.md"
click node_node_nolan "https://github.com/kunalamin/mypka/blob/main/Team/Nolan - HR/AGENTS.md"
click node_node_pax "https://github.com/kunalamin/mypka/blob/main/Team/Pax - Researcher/AGENTS.md"
click node_node_penn "https://github.com/kunalamin/mypka/blob/main/Team/Penn - Journal Writer/AGENTS.md"
click node_node_team_inbox "https://github.com/kunalamin/mypka/blob/main/Team Inbox/README.md"
click node_node_deliverables "https://github.com/kunalamin/mypka/blob/main/Deliverables/README.md"
click node_node_pkm "https://github.com/kunalamin/mypka/blob/main/PKM/INDEX.md"
click node_node_my_life "https://github.com/kunalamin/mypka/blob/main/PKM/My Life/README.md"
click node_node_crm "https://github.com/kunalamin/mypka/blob/main/PKM/CRM/INDEX.md"
click node_node_documents "https://github.com/kunalamin/mypka/blob/main/PKM/Documents/INDEX.md"
click node_node_journal "https://github.com/kunalamin/mypka/blob/main/PKM/Journal/INDEX.md"
click node_node_images "https://github.com/kunalamin/mypka/blob/main/PKM/Images/INDEX.md"
click node_node_team_knowledge "https://github.com/kunalamin/mypka/blob/main/Team Knowledge/INDEX.md"
click node_node_guidelines "https://github.com/kunalamin/mypka/blob/main/Team Knowledge/Guidelines/INDEX.md"
click node_node_sops "https://github.com/kunalamin/mypka/blob/main/Team Knowledge/SOPs/INDEX.md"
click node_node_workstreams "https://github.com/kunalamin/mypka/blob/main/Team Knowledge/Workstreams/INDEX.md"
click node_node_extensions "https://github.com/kunalamin/mypka/blob/main/Extensions/INDEX.md"
click node_node_ext_spec "https://github.com/kunalamin/mypka/blob/main/docs/extension-spec.md"
click node_node_assets "https://github.com/kunalamin/mypka/tree/main/assets/team"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_llm_tool,node_node_adapter_prompt,node_node_root_agents toneBlue
class node_node_agent_index,node_node_larry,node_node_nolan,node_node_pax,node_node_penn toneAmber
class node_node_pkm,node_node_my_life,node_node_crm,node_node_documents,node_node_journal,node_node_images toneMint
class node_node_team_inbox,node_node_deliverables toneRose
class node_node_team_knowledge,node_node_guidelines,node_node_sops,node_node_workstreams toneIndigo
class node_node_extensions,node_node_ext_spec,node_node_assets toneTeal
```

## Components

### Control plane

Root-level governance, bootstrap prompt, and agent routing contracts.

- **LLM client**: external runtime · Claude Code, Codex CLI, Gemini CLI, Cursor, or similar tool that reads and writes the vault.
- [Adapter prompt](https://github.com/kunalamin/mypka/blob/main/ADAPTER-PROMPT.md): bootstrap prompt · Initializes the workspace and generates a tool-specific pointer file. · `ADAPTER-PROMPT.md`
- [Global AGENTS](https://github.com/kunalamin/mypka/blob/main/AGENTS.md): control contract · Root source of truth for repository behavior and agent instructions. · `AGENTS.md`

### Agent layer

Specialist roles and their routing table.

- [Agent index](https://github.com/kunalamin/mypka/blob/main/Team/agent-index.md): routing table · Maps requests to the right specialist and defines team entry points. · `Team/agent-index.md`
- [Larry](https://github.com/kunalamin/mypka/blob/HEAD/Team/Larry%20-%20Orchestrator/AGENTS.md): orchestrator · Primary coordinator and librarian; all user interaction flows through him. · `Team/Larry - Orchestrator/AGENTS.md`
- [Nolan](https://github.com/kunalamin/mypka/blob/HEAD/Team/Nolan%20-%20HR/AGENTS.md): HR specialist · Handles hiring and talent acquisition workflows. · `Team/Nolan - HR/AGENTS.md`
- [Pax](https://github.com/kunalamin/mypka/blob/HEAD/Team/Pax%20-%20Researcher/AGENTS.md): research specialist · Handles deep research and sourcing work. · `Team/Pax - Researcher/AGENTS.md`
- [Penn](https://github.com/kunalamin/mypka/blob/HEAD/Team/Penn%20-%20Journal%20Writer/AGENTS.md): journal specialist · Handles journal writing, filing, and normalization of captured material. · `Team/Penn - Journal Writer/AGENTS.md`

### Canonical knowledge

Markdown knowledge vault organized by domain slices and linked notes.

- [PKM](https://github.com/kunalamin/mypka/blob/main/PKM/INDEX.md): knowledge vault · Canonical Markdown knowledge store for the repository. · `PKM/INDEX.md`
- [My Life](https://github.com/kunalamin/mypka/blob/HEAD/PKM/My%20Life/README.md): personal framework · Main personal operating model organized into goals, habits, topics, projects, and key elements. · `PKM/My Life/README.md`
- [CRM](https://github.com/kunalamin/mypka/blob/main/PKM/CRM/INDEX.md): people knowledge · People and organization notes. · `PKM/CRM/INDEX.md`
- [Documents](https://github.com/kunalamin/mypka/blob/main/PKM/Documents/INDEX.md): document vault · Important personal documents and reference materials. · `PKM/Documents/INDEX.md`
- [Journal](https://github.com/kunalamin/mypka/blob/main/PKM/Journal/INDEX.md): chronological notes · Daily notes and time-ordered capture. · `PKM/Journal/INDEX.md`
- [Images](https://github.com/kunalamin/mypka/blob/main/PKM/Images/INDEX.md): media index · Dated media references and image-linked notes. · `PKM/Images/INDEX.md`

### Working areas

Inbound capture and transient deliverables used during processing.

- [Team Inbox](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Inbox/README.md): capture inbox · Untrusted input boundary for screenshots, voice memos, links, and rough thoughts. · `Team Inbox/README.md`
- [Deliverables](https://github.com/kunalamin/mypka/blob/main/Deliverables/README.md): work surface · Transient workspace for research briefs, workups, and multi-file artifacts. · `Deliverables/README.md`

### Operating procedures

Team playbooks and workflow standards.

- [Team Knowledge](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Knowledge/INDEX.md): playbooks · Guidelines, SOPs, and workstreams that define how the team operates. · `Team Knowledge/INDEX.md`
- [Guidelines](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Knowledge/Guidelines/INDEX.md): standards · Static conventions such as naming rules. · `Team Knowledge/Guidelines/INDEX.md`
- [SOPs](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Knowledge/SOPs/INDEX.md): procedures · Atomic procedures for repeatable tasks. · `Team Knowledge/SOPs/INDEX.md`
- [Workstreams](https://github.com/kunalamin/mypka/blob/HEAD/Team%20Knowledge/Workstreams/INDEX.md): workflows · Multi-step, multi-agent operating flows. · `Team Knowledge/Workstreams/INDEX.md`

### Docs and extensions

Repository-level documentation, extension scaffold, and supporting assets.

- [Extensions](https://github.com/kunalamin/mypka/blob/main/Extensions/INDEX.md): extensibility slot · Optional add-ons and architectural extension point. · `Extensions/INDEX.md`
- [Extension spec](https://github.com/kunalamin/mypka/blob/main/docs/extension-spec.md): specification · Defines how extensions fit the scaffold. · `docs/extension-spec.md`
- [Assets](https://github.com/kunalamin/mypka/tree/main/assets/team): media support · Visual and media assets for documentation and team avatars. · `assets/team`

## Connections

- LLM client → Adapter prompt: bootstraps · The runtime starts from the adapter prompt to initialize the workspace.
- Adapter prompt → Global AGENTS: loads · Bootstrap points the tool at repository-wide operating rules.
- Global AGENTS → Agent index: delegates · Global instructions route requests through the team index.
- Agent index → Larry: routes to · Larry is the primary entry and coordination point.
- Agent index → Nolan: routes to · Talent and hiring tasks go to Nolan.
- Agent index → Pax: routes to · Research and sourcing tasks go to Pax.
- Agent index → Penn: routes to · Writing, filing, and normalization tasks go to Penn.
- Larry → Team Inbox: ingests · Larry helps move raw inputs from inbox to structured work.
- Larry → Deliverables: assembles · Larry aggregates multi-specialist outputs into deliverables.
- Penn → PKM: files into · Penn normalizes captured information into canonical notes.
- Pax → Deliverables: writes · Research outputs are staged in the working area.
- Nolan → Deliverables: produces · Hiring workups and artifacts live in deliverables first.
- Team Inbox → Penn: processed by · Inbox items are cleaned up and filed through Penn or Larry.
- Team Inbox → Larry: triaged by · Larry can directly triage incoming unstructured inputs.
- Deliverables → PKM: promoted to · Useful work products are canonicalized into the knowledge vault.
- PKM → My Life: contains · The personal operating model is the central semantic slice.
- PKM → CRM: contains · People and organizations live in the CRM slice.
- PKM → Documents: contains · Important documents are stored here.
- PKM → Journal: contains · Chronological capture is stored here.
- PKM → Images: contains · Dated image references are stored here.
- Team Knowledge → Guidelines: organizes · Static standards are grouped under guidelines.
- Team Knowledge → SOPs: organizes · Atomic procedures are grouped under SOPs.
- Team Knowledge → Workstreams: organizes · Multi-step workflows are grouped under workstreams.
- Workstreams → PKM: operates on · Workstreams act on the vault as the source of truth.
- Extension spec → Extensions: defines · The spec describes how extensions plug into the scaffold.
- Assets → Global AGENTS: supports · Assets support documentation and team presentation.
- Global AGENTS → Team Knowledge: references · Operating instructions point to team playbooks and procedures.