docs: add session domain model diagram by norrietaylor · Pull Request #262 · gominimal/minimal

norrietaylor · 2026-05-29T18:22:08Z

Adds docs/session-domain-diag.md: domain model for the session architecture.

Covers:

Session (workload) / Provider (creator + host) vernacular
Class diagram of Minimal client → Socket discovery → Provider implementations (minimald, minvmd, hosted, cloud)
Local Linux deployment flow
Local macOS deployment flow (no native minimald; sessions reached via VM-hosted minimald proxied to host)

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added comprehensive Session domain documentation: clear terminology (Session, Provider), how discovery and connections work, architecture diagrams, platform deployment scenarios (Linux/macOS), VM/socket proxying and lifecycle behavior, startup/bootstrap rules (scan/start providers), stale-socket handling, and a glossary clarifying hosting lifecycles and future backend placeholders.

coderabbitai · 2026-05-29T18:22:23Z

Warning

Review limit reached

@norrietaylor, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 13 minutes and 26 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c9c5d8fc-a027-4ac1-8116-f9569e0acf9e

📥 Commits

Reviewing files that changed from the base of the PR and between 05c018a and ad5849e.

📒 Files selected for processing (1)

docs/session-domain-diag.md

📝 Walkthrough

Walkthrough

This PR adds docs/session-domain-diag.md, a new document defining Session and Provider terminology, deployment topologies (Linux/macOS), socket lifecycle and proxying behavior, bootstrap/startup scanning rules, and a glossary of terms.

Changes

Session Domain Model Documentation

Layer / File(s)	Summary
Core domain model and deployment architecture `docs/session-domain-diag.md`	Introduces Session and Provider terminology, Mermaid diagrams covering relationships and local deployment scenarios (Linux minimald/minvmd, macOS VM-hosted sessions), socket lifecycle ownership and stale-socket detection, VM socket proxying behavior, startup/bootstrap scanning rules, and a glossary mapping domain terms.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A domain is born in words and lines,
Sessions and Providers align,
With sockets dancing through the air,
Diagrams mapping everywhere—
Minimal's vision, crystal clear! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add session domain model diagram' directly and concisely describes the main change—adding documentation with domain model diagrams for the session architecture.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/session-domain-diag.md (1)
138-138: ⚡ Quick win

Clarify the stale socket detection mechanism.

Line 138 presents two alternatives ("Connect-and-prune or liveness-check") without specifying which approach is actually used. This ambiguity may confuse readers trying to understand the exact behavior. Consider specifying the implemented mechanism or documenting when each approach applies.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/session-domain-diag.md` at line 138, Clarify which stale-socket
detection strategy `Minimal` uses and how it works: explicitly state whether
`Minimal` performs a connect-and-prune on discovered `<pid>.sock` files
(attempts a socket connect and removes the file if the connect/handshake fails
or times out) or relies on a periodic liveness-check/heartbeat, and include the
timeout/retry behavior and when pruning occurs (on discovery vs background
sweep) so readers know the exact implemented mechanism and any fallback
behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/session-domain-diag.md`:
- Around line 162-174: The glossary table is broken by the blockquote note so
the final row "| Minimal | Client process; ..." is not included in the table;
move the entire "Minimal" table row so it appears immediately before the
blockquote (i.e., make the table contiguous by placing the "| Minimal | Client
process; discovers providers..." row above the "> Note:" line) so the Markdown
table renders correctly; ensure the pipe/column formatting matches the other
rows.

---

Nitpick comments:
In `@docs/session-domain-diag.md`:
- Line 138: Clarify which stale-socket detection strategy `Minimal` uses and how
it works: explicitly state whether `Minimal` performs a connect-and-prune on
discovered `<pid>.sock` files (attempts a socket connect and removes the file if
the connect/handshake fails or times out) or relies on a periodic
liveness-check/heartbeat, and include the timeout/retry behavior and when
pruning occurs (on discovery vs background sweep) so readers know the exact
implemented mechanism and any fallback behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d33975cb-02aa-436e-8ae6-83a738fcd496

📥 Commits

Reviewing files that changed from the base of the PR and between b65c726 and a3295b7.

📒 Files selected for processing (1)

docs/session-domain-diag.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Move the Minimal row above the blockquote so the table renders. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

0chroma · 2026-06-01T08:01:37Z

+
+    class Socket {
+        <<connection>>
+        +path: $HOME/.minimal/local/[pid].sock


On linux at least, might be worth considering putting this in XDG_RUNTIME_DIR to be XDG compliant, see https://wiki.archlinux.org/title/XDG_Base_Directory

since that dir is created with strict perms and is usually on tmpfs, runtime sockets won't risk polluting the filesystem or leaking to other users, will get cleaned up if the user's session dies. Also more predictable, in ~/.minimal someone may delete it thinking it's a stray config file.

Good call. XDG_RUNTIME_DIR is the place for this on linux. On macOS it is less clear.

For now, I am going to remove references to definitive socket paths in this PR. It is an implementation detail and specifying it is not my goal right now

In the current code the socket lives with the provider config at $XDG_STATE_DIR/minimal/providers/<name>/ssh.sock Now would be the best time to change it!

minimal/crates/minimald/src/main.rs

Lines 27 to 64 in 3d4ce47

pub fn minimal_state_dir(&self) -> DaemonAbsPath {

match &self.global_args.minimal_dir {

Some(p) => p.resolve().unwrap(),

None => DaemonAbsPath::try_new(

Utf8PathBuf::from_path_buf(

dirs::state_dir()

.unwrap_or_else(|| dirs::home_dir().unwrap().join(".local/state"))

.join("minimal"),

)

.unwrap(),

)

.unwrap(),

}

}

/// Returns the path to base directory for caching

/// based on command-line arguments.

pub fn minimal_cache_dir(&self) -> DaemonAbsPath {

DaemonAbsPath::try_new(

Utf8PathBuf::from_path_buf(

dirs::cache_dir()

.unwrap_or_else(|| dirs::home_dir().unwrap().join(".local/cache"))

.join("minimal"),

)

.unwrap(),

)

.unwrap()

}

/// Returns the path to the directory containing sockets/info about this daemon for clients.

pub fn client_instance_dir(&self) -> DaemonAbsPath {

let instance_num = match &self.command {

Command::Run(ListenArgs { instance_num }) => *instance_num,

_ => 0,

};

sub_path!(self.minimal_state_dir(), "providers")

.join(&DaemonRelPath::try_new(format!("local-{instance_num}")).unwrap())

}

Definitive socket paths and stale-socket detection are implementation details, outside the scope of the domain model diagram. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai Bot reviewed May 29, 2026

View reviewed changes

Comment thread docs/session-domain-diag.md Outdated

docs: add session domain model diagram

08d072c

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

norrietaylor force-pushed the docs/session-architecture branch from 5613e95 to 08d072c Compare May 29, 2026 18:25

docs: keep glossary table contiguous

a8948f7

Move the Minimal row above the blockquote so the table renders. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

norrietaylor enabled auto-merge (squash) May 29, 2026 20:08

0chroma reviewed Jun 1, 2026

View reviewed changes

norrietaylor force-pushed the docs/session-architecture branch from 05c018a to 3d5b3f1 Compare June 1, 2026 18:36

docs(sessions): remove socket paths from domain model

ad5849e

Definitive socket paths and stale-socket detection are implementation details, outside the scope of the domain model diagram. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

norrietaylor force-pushed the docs/session-architecture branch from 3d5b3f1 to ad5849e Compare June 1, 2026 18:38

twitchyliquid64 approved these changes Jun 1, 2026

View reviewed changes

norrietaylor merged commit 3d4ce47 into main Jun 1, 2026
9 checks passed

norrietaylor deleted the docs/session-architecture branch June 1, 2026 19:36

bryan-minimal mentioned this pull request Aug 12, 2026

fix(common): contain jaq parser panics in jq::parse_file, and wire the fuzz dictionaries #1209

Merged

Navigation Menu

Uh oh!

docs: add session domain model diagram - #262

docs: add session domain model diagram#262
norrietaylor merged 3 commits into
mainfrom
docs/session-architecture

norrietaylor commented May 29, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 29, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

0chroma Jun 1, 2026

Uh oh!

norrietaylor Jun 1, 2026

Uh oh!

twitchyliquid64 Jun 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	pub fn minimal_state_dir(&self) -> DaemonAbsPath {
	match &self.global_args.minimal_dir {
	Some(p) => p.resolve().unwrap(),
	None => DaemonAbsPath::try_new(
	Utf8PathBuf::from_path_buf(
	dirs::state_dir()
	.unwrap_or_else(\|\| dirs::home_dir().unwrap().join(".local/state"))
	.join("minimal"),
	)
	.unwrap(),
	)
	.unwrap(),
	}
	}

	/// Returns the path to base directory for caching
	/// based on command-line arguments.
	pub fn minimal_cache_dir(&self) -> DaemonAbsPath {
	DaemonAbsPath::try_new(
	Utf8PathBuf::from_path_buf(
	dirs::cache_dir()
	.unwrap_or_else(\|\| dirs::home_dir().unwrap().join(".local/cache"))
	.join("minimal"),
	)
	.unwrap(),
	)
	.unwrap()
	}

	/// Returns the path to the directory containing sockets/info about this daemon for clients.
	pub fn client_instance_dir(&self) -> DaemonAbsPath {
	let instance_num = match &self.command {
	Command::Run(ListenArgs { instance_num }) => *instance_num,
	_ => 0,
	};
	sub_path!(self.minimal_state_dir(), "providers")
	.join(&DaemonRelPath::try_new(format!("local-{instance_num}")).unwrap())
	}

Uh oh!

Conversation

norrietaylor commented May 29, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

0chroma Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

norrietaylor Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

twitchyliquid64 Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

norrietaylor commented May 29, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 29, 2026 •

edited

Loading