# roktas/ellipses architecture

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

- Interactive diagram: https://gitdiagram.com/roktas/ellipses
- Repository: https://github.com/roktas/ellipses

## Overview

Ellipses is a static code-reuse tool: users configure provider repositories of named symbols, put inclusion directives in client files, then compile, update, or decompile those files. The client parses and expands directives, tracks generated content in a lock file, and writes changed sources; the server resolves symbol dependencies and reads their payload files. The graph also preserves server dump/validation and client validation surfaces. Relationships are limited to excerpted calls or README-documented behavior; unsampled CLI wiring is not inferred.

Main entry points: [`lib/ellipses/client/application.rb`](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/application.rb) (Client application), [`lib/ellipses/client/repository.rb`](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/repository.rb) (Client repository), [`lib/ellipses/server/repository.rb`](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/repository.rb) (Server repository), [`lib/ellipses/client/source.rb`](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/source.rb) (Client source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflow"]
  node_client_cli["Client CLI<br/>[cli.rb]"]
  node_client_app["Client application<br/>[application.rb]"]
  node_client_source["Client source<br/>[source.rb]"]
  node_client_repo["Client repository<br/>[repository.rb]"]
  node_client_meta["Lock metadata<br/>[meta.rb]"]
  node_client_meta_file["Lock file<br/>[meta_file.rb]"]
  node_client_commands["Edit commands"]
end

subgraph group_provider["Provider repositories"]
  node_provider_files[("Provider source files")]
  node_server_cli["Server CLI<br/>[cli.rb]"]
  node_server_app["Server application<br/>[application.rb]"]
  node_server_repo["Server repository<br/>[repository.rb]"]
  node_symbols["Symbol resolver<br/>[symbols.rb]"]
  node_server_meta["Provider metadata<br/>[meta.rb]"]
  node_server_meta_file["Provider config file<br/>[meta_file.rb]"]
end

subgraph group_domain["Shared processing"]
  node_directive_parser["Directive parser<br/>[parser.rb]"]
  node_directive["Directive model<br/>[directive.rb]"]
  node_line_engine["Line processing<br/>[lines.rb]"]
  node_support["Shared support"]
end

node_user(("Developer"))

node_user -->|"runs commands"| node_client_cli
node_client_cli -.->|"invokes workflow"| node_client_app
node_client_app -->|"registers sources"| node_client_repo
node_client_app -->|"recompiles sources"| node_client_repo
node_client_app -->|"saves state"| node_client_repo
node_client_app -->|"writes lock file"| node_client_meta_file
node_client_repo -->|"loads sources"| node_client_source
node_client_source -->|"parses directives"| node_directive_parser
node_directive_parser -.->|"creates directives"| node_directive
node_client_source -.->|"processes lines"| node_line_engine
node_client_repo -->|"dumps registrations"| node_client_meta
node_client_app -->|"loads lock state"| node_client_meta_file
node_client_app -.->|"supports edit operations"| node_client_commands
node_user -->|"initializes client"| node_client_app
node_user -->|"compiles files"| node_client_app
node_user -->|"updates files"| node_client_app
node_user -->|"decompiles files"| node_client_app
node_user -->|"validates client"| node_client_app
node_user -.->|"runs server tools"| node_server_cli
node_server_cli -.->|"requests dump"| node_server_app
node_server_app -->|"loads repository"| node_server_repo
node_server_app -->|"resolves requested symbols"| node_server_repo
node_server_repo -->|"walks dependencies"| node_symbols
node_symbols -->|"reads payloads"| node_provider_files
node_server_repo -->|"reads configuration"| node_server_meta_file
node_server_meta_file -.->|"parses metadata"| node_server_meta
node_user -->|"authors symbols"| node_provider_files
node_client_app -.->|"uses shared utilities"| node_support

click node_client_cli "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/cli.rb"
click node_client_app "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/application.rb"
click node_directive_parser "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/parser.rb"
click node_directive "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/directive.rb"
click node_line_engine "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/lines.rb"
click node_client_source "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/source.rb"
click node_client_repo "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/repository.rb"
click node_client_meta "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/meta.rb"
click node_client_meta_file "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/meta_file.rb"
click node_client_commands "https://github.com/roktas/ellipses/tree/dev/lib/ellipses/client/commands"
click node_server_cli "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/cli.rb"
click node_server_app "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/application.rb"
click node_server_repo "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/repository.rb"
click node_symbols "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/symbols.rb"
click node_server_meta "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/meta.rb"
click node_server_meta_file "https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/meta_file.rb"
click node_support "https://github.com/roktas/ellipses/tree/dev/lib/ellipses/support"

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_client_cli,node_client_app,node_client_source,node_client_repo,node_client_meta,node_client_meta_file,node_client_commands toneBlue
class node_provider_files,node_server_cli,node_server_app,node_server_repo,node_symbols,node_server_meta,node_server_meta_file toneAmber
class node_directive_parser,node_directive,node_line_engine,node_support toneMint
class node_user toneIndigo
```

## Components

### Client workflow

- [Client CLI](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/cli.rb): `lib/ellipses/client/cli.rb`
- [Client application](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/application.rb): `lib/ellipses/client/application.rb`
- [Client source](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/source.rb): `lib/ellipses/client/source.rb`
- [Client repository](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/repository.rb): `lib/ellipses/client/repository.rb`
- [Lock metadata](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/meta.rb): `lib/ellipses/client/meta.rb`
- [Lock file](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/meta_file.rb): `lib/ellipses/client/meta_file.rb`
- [Edit commands](https://github.com/roktas/ellipses/tree/dev/lib/ellipses/client/commands): `lib/ellipses/client/commands`

### Provider repositories

- **Provider source files**
- [Server CLI](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/cli.rb): `lib/ellipses/server/cli.rb`
- [Server application](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/application.rb): `lib/ellipses/server/application.rb`
- [Server repository](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/repository.rb): `lib/ellipses/server/repository.rb`
- [Symbol resolver](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/symbols.rb): `lib/ellipses/server/symbols.rb`
- [Provider metadata](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/meta.rb): `lib/ellipses/server/meta.rb`
- [Provider config file](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/server/meta_file.rb): `lib/ellipses/server/meta_file.rb`

### Shared processing

- [Directive parser](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/parser.rb): `lib/ellipses/client/parser.rb`
- [Directive model](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/directive.rb): `lib/ellipses/client/directive.rb`
- [Line processing](https://github.com/roktas/ellipses/blob/dev/lib/ellipses/client/lines.rb): `lib/ellipses/client/lines.rb`
- [Shared support](https://github.com/roktas/ellipses/tree/dev/lib/ellipses/support): `lib/ellipses/support`

### Other components

- **Developer**

## Connections

- Developer → Client CLI: runs commands
- Client CLI → Client application: invokes workflow
- Client application → Client repository: registers sources (evidence: `lib/ellipses/client/application.rb`)
- Client application → Client repository: recompiles sources (evidence: `lib/ellipses/client/application.rb`)
- Client application → Client repository: saves state (evidence: `lib/ellipses/client/application.rb`)
- Client application → Lock file: writes lock file (evidence: `lib/ellipses/client/application.rb`)
- Client repository → Client source: loads sources (evidence: `lib/ellipses/client/repository.rb`)
- Client source → Directive parser: parses directives
- Directive parser → Directive model: creates directives
- Client source → Line processing: processes lines
- Client repository → Lock metadata: dumps registrations (evidence: `lib/ellipses/client/repository.rb`)
- Client application → Lock file: loads lock state (evidence: `lib/ellipses/client/application.rb`)
- Client application → Edit commands: supports edit operations
- Developer → Client application: initializes client
- Developer → Client application: compiles files
- Developer → Client application: updates files
- Developer → Client application: decompiles files
- Developer → Client application: validates client
- Developer → Server CLI: runs server tools
- Server CLI → Server application: requests dump
- Server application → Server repository: loads repository (evidence: `lib/ellipses/server/application.rb`)
- Server application → Server repository: resolves requested symbols (evidence: `lib/ellipses/server/application.rb`)
- Server repository → Symbol resolver: walks dependencies (evidence: `lib/ellipses/server/repository.rb`)
- Symbol resolver → Provider source files: reads payloads (evidence: `lib/ellipses/server/symbols.rb`)
- Server repository → Provider config file: reads configuration (evidence: `lib/ellipses/server/repository.rb`)
- Provider config file → Provider metadata: parses metadata
- Developer → Provider source files: authors symbols
- Client application → Shared support: uses shared utilities