Document sample and hardware domain model

[ceej640]

Closes #9.

Summary:

• Add architecture docs for sample/hardware domain boundaries and standard operations.
• Define reusable sample tracking metrics across organisms and microscopes.
• Add a hardware profile checklist for new device profiles and link the docs from the README.

Verification:

• git diff --check

[pskeshu]

Can we make some like Oxygen or equivalent automated documents, tutorials etc for gently? We need to take a Full Stack Microscopy perspective, and hardware is one of those stacks. The broader documentation can cover all aspects of system integration in microscopy.

…

On Sat, 30 May 2026 at 22:06, ceej640 ***@***.***> wrote: Closes #9 <https://github.com/pskeshu/gently/issues/9>. Summary: - Add architecture docs for sample/hardware domain boundaries and standard operations. - Define reusable sample tracking metrics across organisms and microscopes. - Add a hardware profile checklist for new device profiles and link the docs from the README. Verification: - git diff --check ------------------------------ You can view, comment on, or merge this pull request online at: https://github.com/pskeshu/gently/pull/27 Commit Summary - de05bb4 <pskeshu@de05bb4> Document sample and hardware domain model File Changes (4 files <https://github.com/pskeshu/gently/pull/27/files>) - *M* README.md <https://github.com/pskeshu/gently/pull/27/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5> (3) - *A* docs/architecture/hardware-profile-template.md <https://github.com/pskeshu/gently/pull/27/files#diff-0b5cb3101e9893fe228004a5665e5069c18a251d0fd5094a05a35ae4b0116d54> (97) - *A* docs/architecture/sample-hardware-domains.md <https://github.com/pskeshu/gently/pull/27/files#diff-dcf05f8edcd7850d82ee7ec342c01dc1191cc9ba27abf4a0630c52c1632d8e94> (104) - *A* docs/architecture/sample-tracking-metrics.md <https://github.com/pskeshu/gently/pull/27/files#diff-dca0c48e8cbf77184f42dd22492b88ec7d1853b09b6a0b4a031a3b9c784f8017> (122) Patch Links: - https://github.com/pskeshu/gently/pull/27.patch - https://github.com/pskeshu/gently/pull/27.diff — Reply to this email directly, view it on GitHub <https://github.com/pskeshu/gently/pull/27?email_source=notifications&email_token=ABVNN4G4HANE7RWNPRUCIAD45OHRNA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF4ZTONZVGM4DMMJRGGTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVRTG633UMVZF6Y3MNFRWW>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVNN4BK3PRX5MFGQLWHK4T45OHRNAVCNFSM6AAAAACZUCKCOSVHI2DSMVQWIX3LMV43ASLTON2WKOZUGU2TMMRZHAZTGNA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Kesavan

[ceej640]

Yes. I think the docs should grow into a Doxygen/Sphinx/MkDocs-style documentation system for Gently, but with a Full Stack Microscopy organization rather than only API reference pages.

I would not try to put all of that into this PR. This PR gives some source material: sample/hardware vocabulary, domain boundaries, tracking metrics, and hardware profile checklists. A follow-up documentation PR could turn that into a generated/tutorial site with sections for:

• sample preparation and sample state
• hardware/device layer and microscope profiles
• perception and data products
• planning and experimental intent
• acquisition/control loops
• storage, provenance, and export
• deployment/operator workflows for a real microscope server

That would make hardware one stack in a broader system-integration view, instead of documenting it as an isolated device layer.

[ceej640]

Follow-up implemented from this thread in commit 8e6a0d7.

I added a lightweight generated-docs structure:

• mkdocs.yml
• docs/index.md
• docs/full-stack-microscopy.md
• README links into the new docs entry points

The new overview frames Gently as a full-stack microscopy system: experimental intent, sample preparation, hardware integration, acquisition, perception, closed-loop decisions, data/provenance, and operator experience. Hardware is documented as one stack in that broader system rather than as an isolated device layer.

Verification:

• git diff --check