# darafarm/lightcodepedia architecture

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

- Interactive diagram: https://gitdiagram.com/darafarm/lightcodepedia
- Repository: https://github.com/darafarm/lightcodepedia

## Overview

Lightcode is a Streamlit-based environment for authoring and exploring Python/YAML modules. A user enters the app, accesses the module editor, loads or previews a module, and can save scripts or serialize module definitions. Separate capabilities include account/repository access, module diagrams, and execution. The graph reflects only relationships visible in excerpts or the source index; YAML module catalogs and several UI features are present in the tree but their runtime wiring was not sampled.

Main entry points: [`lightcode.py`](https://github.com/darafarm/lightcodepedia/blob/main/lightcode.py) (Public API), [`pages/_play.py`](https://github.com/darafarm/lightcodepedia/blob/main/pages/_play.py) (Play editor), [`usecases/common/backend/module_loader.py`](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_loader.py) (YAML loader), [`usecases/common/backend/user_manager.py`](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/user_manager.py) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry and UI"]
  node_main["App entry<br/>[main.py]"]
  node_lightcode["Public API<br/>[lightcode.py]"]
  node_common["UI utilities<br/>[common.py]"]
  node_play["Play editor<br/>[_play.py]"]
  node_about["About view<br/>[about_box.py]"]
end

subgraph group_modules["Module authoring"]
  node_importer["Module import<br/>[module_importer.py]"]
  node_loader["YAML loader<br/>[module_loader.py]"]
  node_wrapper["Module model<br/>[module_wrapper.py]"]
  node_decorator["Diagram generation"]
  node_dumper["YAML serialization<br/>[module_dumper.py]"]
  node_yamlcatalog["Module catalog"]
end

subgraph group_backend["Runtime backend"]
  node_services["Code services<br/>[services.py]"]
  node_env["Settings loader<br/>[env_manager.py]"]
  node_tracing["Execution tracing<br/>[tracing.py]"]
end

subgraph group_accounts["Accounts and storage"]
  node_users["User management<br/>[user_manager.py]"]
  node_userstate["User state<br/>[user_state.py]"]
  node_files["File access<br/>[file_access.py]"]
end

node_user(("User"))
node_github[("GitHub repository")]
node_sheets[("Google Sheets")]
node_streamlit[("Streamlit session")]

node_user -->|"opens"| node_main
node_main -->|"imports"| node_lightcode
node_lightcode -->|"re-exports"| node_common
node_lightcode -->|"re-exports"| node_importer
node_lightcode -->|"re-exports"| node_dumper
node_lightcode -->|"re-exports"| node_users
node_lightcode -->|"re-exports"| node_wrapper
node_lightcode -->|"re-exports"| node_about
node_user -.->|"uses editor"| node_play
node_play -->|"uses API"| node_lightcode
node_play -->|"previews modules"| node_importer
node_play -->|"builds diagrams"| node_decorator
node_play -->|"serializes modules"| node_dumper
node_importer -->|"loads modules"| node_loader
node_importer -->|"accesses files"| node_files
node_loader -->|"reads modules"| node_files
node_loader -->|"creates models"| node_wrapper
node_decorator -.->|"inspects models"| node_wrapper
node_dumper -->|"serializes model"| node_wrapper
node_services -->|"loads YAML"| node_loader
node_services -->|"saves scripts"| node_files
node_files -.->|"reads and writes"| node_github
node_users -->|"loads credentials"| node_env
node_users -->|"uses session state"| node_userstate
node_users -.->|"reads and updates"| node_sheets
node_common -.->|"updates session"| node_streamlit
node_yamlcatalog -.->|"loaded as modules"| node_loader

click node_main "https://github.com/darafarm/lightcodepedia/blob/main/main.py"
click node_lightcode "https://github.com/darafarm/lightcodepedia/blob/main/lightcode.py"
click node_common "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/common.py"
click node_play "https://github.com/darafarm/lightcodepedia/blob/main/pages/_play.py"
click node_about "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/view/about_box.py"
click node_importer "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_importer.py"
click node_loader "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_loader.py"
click node_wrapper "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_wrapper.py"
click node_decorator "https://github.com/darafarm/lightcodepedia/blob/main/usecases/module_manager/backend/module_decorator.py"
click node_dumper "https://github.com/darafarm/lightcodepedia/blob/main/usecases/module_manager/backend/module_dumper.py"
click node_services "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/services.py"
click node_env "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/env_manager.py"
click node_tracing "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/tracing.py"
click node_users "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/user_manager.py"
click node_userstate "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/user_state.py"
click node_files "https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/file_access.py"
click node_yamlcatalog "https://github.com/darafarm/lightcodepedia/tree/main/modules"

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_main,node_lightcode,node_common,node_play,node_about,node_user toneBlue
class node_importer,node_loader,node_wrapper,node_decorator,node_dumper,node_yamlcatalog,node_github,node_sheets,node_streamlit toneAmber
class node_services,node_env,node_tracing toneMint
class node_users,node_userstate,node_files toneRose
```

## Components

### App entry and UI

- [App entry](https://github.com/darafarm/lightcodepedia/blob/main/main.py): `main.py`
- [Public API](https://github.com/darafarm/lightcodepedia/blob/main/lightcode.py): `lightcode.py`
- [UI utilities](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/common.py): `usecases/common/common.py`
- [Play editor](https://github.com/darafarm/lightcodepedia/blob/main/pages/_play.py): `pages/_play.py`
- [About view](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/view/about_box.py): `usecases/common/view/about_box.py`

### Module authoring

- [Module import](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_importer.py): `usecases/common/backend/module_importer.py`
- [YAML loader](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_loader.py): `usecases/common/backend/module_loader.py`
- [Module model](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/module_wrapper.py): `usecases/common/backend/module_wrapper.py`
- [Diagram generation](https://github.com/darafarm/lightcodepedia/blob/main/usecases/module_manager/backend/module_decorator.py): `usecases/module_manager/backend/module_decorator.py`
- [YAML serialization](https://github.com/darafarm/lightcodepedia/blob/main/usecases/module_manager/backend/module_dumper.py): `usecases/module_manager/backend/module_dumper.py`
- [Module catalog](https://github.com/darafarm/lightcodepedia/tree/main/modules): `modules`

### Runtime backend

- [Code services](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/services.py): `usecases/common/backend/services.py`
- [Settings loader](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/env_manager.py): `usecases/common/backend/env_manager.py`
- [Execution tracing](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/tracing.py): `usecases/common/backend/tracing.py`

### Accounts and storage

- [User management](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/user_manager.py): `usecases/common/backend/user_manager.py`
- [User state](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/user_state.py): `usecases/common/backend/user_state.py`
- [File access](https://github.com/darafarm/lightcodepedia/blob/main/usecases/common/backend/file_access.py): `usecases/common/backend/file_access.py`

### Other components

- **User**
- **GitHub repository**
- **Google Sheets**
- **Streamlit session**

## Connections

- User → App entry: opens (evidence: `main.py`)
- App entry → Public API: imports (evidence: `main.py`)
- Public API → UI utilities: re-exports (evidence: `lightcode.py`)
- Public API → Module import: re-exports (evidence: `lightcode.py`)
- Public API → YAML serialization: re-exports (evidence: `lightcode.py`)
- Public API → User management: re-exports (evidence: `lightcode.py`)
- Public API → Module model: re-exports (evidence: `lightcode.py`)
- Public API → About view: re-exports (evidence: `lightcode.py`)
- User → Play editor: uses editor
- Play editor → Public API: uses API (evidence: `pages/_play.py`)
- Play editor → Module import: previews modules (evidence: `pages/_play.py`)
- Play editor → Diagram generation: builds diagrams (evidence: `pages/_play.py`)
- Play editor → YAML serialization: serializes modules (evidence: `pages/_play.py`)
- Module import → YAML loader: loads modules (evidence: `usecases/common/backend/module_importer.py`)
- Module import → File access: accesses files (evidence: `usecases/common/backend/module_importer.py`)
- YAML loader → File access: reads modules (evidence: `usecases/common/backend/module_loader.py`)
- YAML loader → Module model: creates models (evidence: `usecases/common/backend/module_loader.py`)
- Diagram generation → Module model: inspects models (evidence: `usecases/module_manager/backend/module_decorator.py`)
- YAML serialization → Module model: serializes model (evidence: `usecases/module_manager/backend/module_dumper.py`)
- Code services → YAML loader: loads YAML (evidence: `usecases/common/backend/services.py`)
- Code services → File access: saves scripts (evidence: `usecases/common/backend/services.py`)
- File access → GitHub repository: reads and writes
- User management → Settings loader: loads credentials (evidence: `usecases/common/backend/user_manager.py`)
- User management → User state: uses session state (evidence: `usecases/common/backend/user_manager.py`)
- User management → Google Sheets: reads and updates
- UI utilities → Streamlit session: updates session
- Module catalog → YAML loader: loaded as modules