# tg1482/loopy architecture

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

- Interactive diagram: https://gitdiagram.com/tg1482/loopy
- Repository: https://github.com/tg1482/loopy

## Overview

##### What this project is (type + purpose)

**Loopy is a Python library (plus a CLI-like REPL) that implements a sandbox “filesystem” whose entire state lives in a single Python string**. It provides:

- An **in-memory tree model** (directories/files/symlinks)
- A **parser/serializer** between that tree and a single **raw string** representation (XML-ish tags)
- A **filesystem-like API** (`mkdir`, `touch`, `ls`, `cat`, `rm`, `mv`, `grep`, `find`, `glob`, etc.)
- A **bash-style shell runner** (`loopy.shell.run`) with pipes and chaining, plus a REPL (`python -m loopy.shell …`)
- An optional **file-backed mode** that persists the raw string to a `.loopy` file (`FileBackedLoopy`, `load`, `save`)

##### File tree-driven architecture (what the directories imply)

From the tree:

- `src/loopy/`
- `core.py`, `core_v2.py`: likely the **domain model + operations** (tree nodes, path resolution, CRUD, search, serialization)
- `file_store.py`: **persistence adapter** (load/save `.loopy`, file-backed wrapper)
- `shell.py`: **command parsing/execution** and **REPL entry**
- `__init__.py`: public exports (`Loopy`, `FileBackedLoopy`, helpers)
- `examples/`: sample datasets (`*.loopy`) and notebook
- `tests/`: unit tests spanning core, shell, file store, stress/perf
- `stress_test.py`: perf benchmark harness
- `.github/workflows/tests.yml`: CI pipeline to run tests
- `pyproject.toml`: packaging + dependencies + entry points (if any)

This structure strongly suggests a clean separation:
**Core Loopy engine** ↔ **Shell interface** ↔ **File storage adapter**.

##### Input raw string (optional)
⟶ **Parser**
⟶ **In-memory Node Tree (authoritative state)**
##### User operations / shell commands
⟶ **Core operations mutate tree**
##### Serialization on demand
⟶ Tree ⟶ `.raw` string (cached until invalidated by mutation)

##### Shell flow
- Shell `run("...")` / REPL input
⟶ parse into commands
⟶ execute against `Loopy` instance
⟶ optionally pipe outputs between commands
⟶ return final output string(s)

##### File-backed flow
- Mutation command (`touch`, `mkdir`, `rm`, …) against **FileBackedLoopy**
⟶ Core mutation
⟶ triggers `save()` (writes `.loopy` file)

##### Architectural patterns to highlight (specific to Loopy)

- **Core/Adapter separation**
- Core = deterministic, in-memory, no OS I/O
- Adapter = file_store for persistence side effects
- **Command pattern / interpreter**
- shell commands mapped to core operations
- pipelines/chaining as composition mechanism
- **Lazy serialization + cache invalidation**
- `.raw` generated on demand
- cached `.raw` reused until mutation
- **Iterative algorithms**
- README claims “no recursion limits”; useful to note for deep trees

##### What “detailed and separated into many components” means here (practical checklist)

- `Loopy` object (public API)
- Node Tree (state)
- Path resolution + cwd
- CRUD ops (mkdir/touch/rm/mv/cp/ln)
- Search ops (grep/find/glob)
- Parser (raw → tree)
- Serializer (tree → raw)
- Raw cache + invalidation on mutation
- `shell.run()` API
- Shell parser
- Shell executor
- Pipe/chaining engine
- REPL entry (`python -m loopy.shell …`)
- `load()` / `save()`
- `FileBackedLoopy` autosave behavior
- `.loopy` file on disk (external resource)
- Examples (`examples/*.loopy`) as sample inputs (optional but useful)
- CI/tests/benchmarks as non-runtime support (optional layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1 — Context
%% =========================
subgraph "Diagram 1 — Context (High Level)"
direction TB

U["User / Python Code"]:::external
CLI["CLI / REPL User"]:::external

subgraph "Loopy Library (Python Package)"
direction TB
API["Public API Facade (loopy.__init__)"]:::facade
CORE["Core Engine (in-memory filesystem)"]:::core
SHELL["Shell Runner + REPL (loopy.shell)"]:::shell
STORE["Persistence Adapter (loopy.file_store)"]:::adapter
end

DISK[("OS Filesystem\n(.loopy file on disk)")]:::disk
RAW["Raw String Representation\n(XML-ish tags)"]:::state

U -->|"imports/uses"| API
CLI -->|"python -m loopy.shell"| SHELL

API -->|"constructs/uses"| CORE
SHELL -->|"invokes API methods"| CORE

STORE -->|"reads/writes"| DISK
STORE -->|"loads/parses"| RAW
CORE -->|"serializes (on demand)"| RAW
API -->|"exposes load/save"| STORE
end

%% =========================
%% Diagram 2 — Containers / Modules (Repo Accurate)
%% =========================
subgraph "Diagram 2 — Module / Container View (Repo Accurate)"
direction TB

subgraph "src/loopy/"
direction TB
INIT["loopy.__init__\n(Exports: Loopy, FileBackedLoopy, load/save, slugify)"]:::facade
CORE1["loopy.core\n(Core Engine v1)"]:::core
CORE2["loopy.core_v2\n(Core Engine v2 - alternate/new)"]:::core2
SHELLMOD["loopy.shell\n(shell.run, pipelines, REPL entry)"]:::shell
STOREMOD["loopy.file_store\n(load/save, FileBackedLoopy autosave)"]:::adapter
end

DISK2[("OS Filesystem\n*.loopy file")]:::disk

INIT -->|"re-exports"| CORE1
INIT -->|"re-exports"| STOREMOD
INIT -->|"optional: alternate engine"| CORE2

SHELLMOD -->|"calls filesystem API"| CORE1
SHELLMOD -.->|"may target alternate engine"| CORE2

STOREMOD -->|"load(raw)->Loopy"| CORE1
STOREMOD -->|"save(tree.raw)"| DISK2
STOREMOD -->|"ONLY disk I/O"| DISK2

NOTEBOUND["Side-effect boundary:\nCore is pure/in-memory;\nfile_store is the only OS I/O"]:::note
STOREMOD --- NOTEBOUND
end

%% =========================
%% Diagram 3 — Component-level Internals
%% =========================
subgraph "Diagram 3 — Component-level (Internals that Matter)"
direction TB

subgraph "Core Engine (loopy.core / loopy.core_v2)"
direction TB

PARSER["Parser\n(raw string → node tree)"]:::core
TREE[("In-memory Node Tree\n(dirs/files/symlinks)\n(authoritative state)")]:::state
PATHRES["Path Resolution + cwd\n(abs/rel, '..', cd())"]:::core
CRUD["Mutation Ops\nmkdir/touch/write/rm/mv/cp/ln"]:::core
SEARCH["Read/Search Ops\nls/cat/walk/readlink/backlinks\ngrep/find/glob"]:::core
SER["Serializer\n(node tree → raw string)"]:::core
RAWCACHE[("Raw String Cache\n.tree.raw (memoized)\ninvalidated on mutation)")]:::state
ITER["Iterative Algorithms\n(no recursion limits for deep trees)"]:::note

PARSER -->|"builds"| TREE
TREE -->|"queried via"| SEARCH
TREE -->|"mutated via"| CRUD
PATHRES -->|"resolves paths into"| TREE
CRUD -->|"invalidates"| RAWCACHE
SER -->|"generates"| RAWCACHE
TREE -->|"serialized by"| SER
ITER --- TREE
end

subgraph "Shell (loopy.shell)"
direction TB
RUN["shell.run(cmd, tree)\n(bash-style runner)"]:::shell
CMDPARSE["Command Parser\n(tokenize/args, builtins map)"]:::shell
EXEC["Executor\n(invokes Loopy API, maintains context)"]:::shell
PIPE["Pipeline + Chaining Engine\n'|' ';' '&&' '||'"]:::shell
REPL["REPL Loop\npython -m loopy.shell\nread → eval → print"]:::shell

REPL -->|"reads input"| RUN
RUN -->|"parses"| CMDPARSE
CMDPARSE -->|"builds plan"| PIPE
PIPE -->|"drives"| EXEC
EXEC -->|"calls"| PATHRES
EXEC -->|"calls"| CRUD
EXEC -->|"calls"| SEARCH
PIPE -->|"pipes output to next cmd"| PIPE
end

subgraph "Persistence Adapter (loopy.file_store)"
direction TB
LOAD["load(path)\nread .loopy → raw → Loopy"]:::adapter
SAVE["save(tree, path)\ntree.raw → write .loopy"]:::adapter
FBL["FileBackedLoopy(path)\nwraps Loopy + autosave"]:::adapter
AUTOS["Autosave Hook\n(on mutations)"]:::adapter
OSIO[("Disk I/O\n(read/write .loopy)")]:::disk

LOAD -->|"reads"| OSIO
SAVE -->|"writes"| OSIO
LOAD -->|"passes raw to"| PARSER
SAVE -->|"requests"| RAWCACHE

FBL -->|"delegates to"| CRUD
CRUD -->|"mutation event"| AUTOS
AUTOS -->|"triggers"| SAVE
end

PURENOTE["Core invariants:\n- No OS I/O in core\n- Serialization is pure\n- .raw is lazy + cached until mutation"]:::note
OSIO --- PURENOTE
end

%% =========================
%% Diagram 4 — Sequences (2 key flows)
%% =========================
subgraph "Diagram 4 — Key Sequences (Interaction Flows)"
direction TB

subgraph "Sequence A — shell.run('cd … && cat …')"
direction TB
A1["Input: command string"]:::external
A2["shell.run"]:::shell
A3["Parse + chaining (&&)"]:::shell
A4["Execute: cd"]:::shell
A5["Core: path resolution + cwd update"]:::core
A6["Execute: cat"]:::shell
A7["Core: read file content"]:::core
A8["Output: string"]:::external

A1 -->|"provides"| A2
A2 -->|"calls"| A3
A3 -->|"step1"| A4
A4 -->|"invokes"| A5
A3 -->|"on success step2"| A6
A6 -->|"invokes"| A7
A7 -->|"returns"| A8
end

subgraph "Sequence B — FileBackedLoopy.touch() autosave"
direction TB
B1["User calls FileBackedLoopy.touch(path)"]:::external
B2["FileBackedLoopy wrapper"]:::adapter
B3["Core mutation (touch)"]:::core
B4["Invalidate raw cache"]:::state
B5["save(tree.raw)"]:::adapter
B6["Disk write (.loopy)"]:::disk

B1 -->|"calls"| B2
B2 -->|"delegates"| B3
B3 -->|"invalidates"| B4
B2 -->|"after mutation triggers"| B5
B5 -->|"writes"| B6
end
end

%% =========================
%% Support/Non-runtime Artifacts
%% =========================
subgraph "Repo Support Artifacts (Non-runtime)"
direction TB
EXDIR["Examples Directory\n(sample .loopy datasets)"]:::support
EX1["bookmarks.loopy"]:::support
EX2["knowledge_graph.loopy"]:::support
EX3["org_chart.loopy"]:::support
EX4["product_catalog.loopy"]:::support
EX5["recipes.loopy"]:::support
TESTS["Unit Tests"]:::support
BENCH["Stress / Benchmark Harness"]:::support
CI["CI Workflow"]:::support
PKG["Packaging / Build Config"]:::support

EXDIR -->|"contains"| EX1
EXDIR -->|"contains"| EX2
EXDIR -->|"contains"| EX3
EXDIR -->|"contains"| EX4
EXDIR -->|"contains"| EX5

CI -->|"runs"| TESTS
BENCH -.->|"benchmarks"| CORE1
TESTS -.->|"covers"| CORE1
TESTS -.->|"covers"| SHELLMOD
TESTS -.->|"covers"| STOREMOD
PKG -.->|"defines deps/entry points"| INIT
end

%% =========================
%% Click events (from component_mapping)
%% =========================
click INIT "https://github.com/tg1482/loopy/blob/main/src/loopy/__init__.py"
click CORE1 "https://github.com/tg1482/loopy/blob/main/src/loopy/core.py"
click CORE2 "https://github.com/tg1482/loopy/blob/main/src/loopy/core_v2.py"
click SHELLMOD "https://github.com/tg1482/loopy/blob/main/src/loopy/shell.py"
click STOREMOD "https://github.com/tg1482/loopy/blob/main/src/loopy/file_store.py"
click EXDIR "https://github.com/tg1482/loopy/tree/main/examples/"
click EX1 "https://github.com/tg1482/loopy/blob/main/examples/bookmarks.loopy"
click EX2 "https://github.com/tg1482/loopy/blob/main/examples/knowledge_graph.loopy"
click EX3 "https://github.com/tg1482/loopy/blob/main/examples/org_chart.loopy"
click EX4 "https://github.com/tg1482/loopy/blob/main/examples/product_catalog.loopy"
click EX5 "https://github.com/tg1482/loopy/blob/main/examples/recipes.loopy"
click BENCH "https://github.com/tg1482/loopy/blob/main/stress_test.py"
click TESTS "https://github.com/tg1482/loopy/tree/main/tests/"
click CI "https://github.com/tg1482/loopy/blob/main/.github/workflows/tests.yml"
click PKG "https://github.com/tg1482/loopy/blob/main/pyproject.toml"

%% =========================
%% Styles
%% =========================
classDef external fill:#ffffff,stroke:#475569,stroke-width:1.5px,color:#0f172a
classDef facade fill:#dcfce7,stroke:#166534,stroke-width:1.5px,color:#052e16
classDef core fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b4d
classDef core2 fill:#e0e7ff,stroke:#4338ca,stroke-width:1.5px,color:#1e1b4b
classDef shell fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#042f2e
classDef adapter fill:#ffedd5,stroke:#c2410c,stroke-width:1.5px,color:#431407
classDef disk fill:#fee2e2,stroke:#b91c1c,stroke-width:1.8px,color:#450a0a
classDef state fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#422006
classDef note fill:#f1f5f9,stroke:#64748b,stroke-dasharray:4 3,stroke-width:1.2px,color:#0f172a
classDef support fill:#f5f3ff,stroke:#6d28d9,stroke-width:1.2px,color:#2e1065
```
