Skip to content

Commit acd3b84

Browse files
kelly-sovacoolkelly-sovacool
committed
docs: rough diagrams for demo
1 parent f1b4081 commit acd3b84

2 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎docs/demo/index.qmd‎

Whitespace-only changes.

‎docs/guide/index.qmd‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: "Demo"
3+
echo: false
4+
---
5+
6+
## Overview
7+
8+
The diagram below shows how syncweaver coordinates a **source repo** and a **host repo**
9+
through the CCBR/syncweaver orchestrator.
10+
11+
```{mermaid}
12+
sequenceDiagram
13+
actor Dev as Developer
14+
participant Src as Source Repo<br/>(demo-syncweaver-source)
15+
participant SW as Orchestrator<br/>(CCBR/syncweaver)
16+
participant Host as Host Repo<br/>(demo-syncweaver-host)
17+
18+
Note over Src: .github/workflows/<br/>syncweaver-source-dispatch.yml
19+
20+
Dev->>Src: push release tag
21+
Src->>SW: repository_dispatch<br/>(source_repository, ref)
22+
23+
SW->>Host: repository_dispatch<br/>(source_repository, ref)
24+
25+
Note over Host: .github/workflows/<br/>syncweaver-host-update.yml
26+
27+
Host->>Host: resolve source_path<br/>from .syncweaver-lock.json
28+
Host->>Src: fetch code at ref
29+
Host->>Host: vendor code into source_path
30+
Host->>Host: open pull request<br/>with updated vendored code
31+
32+
Note over Host,Src: If the host has local patches...
33+
34+
Dev->>Host: trigger contribute-patch
35+
Note over Host: .github/workflows/<br/>syncweaver-host-contribute-patch.yml
36+
Host->>Src: open pull request<br/>with patch applied upstream
37+
```
38+
39+
## Repository layouts
40+
41+
This view emphasizes a different question than the sequence diagram: which
42+
source repositories are vendored into which host capsules.
43+
44+
```{mermaid}
45+
flowchart LR
46+
subgraph H1[demo-syncweaver-host]
47+
H1A[code/hello]
48+
H1B[code/MOSuite]
49+
end
50+
51+
subgraph H2[MOSuite-create]
52+
H2A[code/MOSuite]
53+
end
54+
55+
subgraph H3[MOSuite-clean]
56+
H3A[code/MOSuite]
57+
end
58+
59+
S1[demo-syncweaver-source<br/>modules/hello]
60+
S2[CCBR/MOSuite<br/>R package source]
61+
62+
S1 --> H1A
63+
S2 --> H1B
64+
S2 --> H2A
65+
S2 --> H3A
66+
```
67+
68+
In these examples, one host capsule can aggregate multiple upstream sources,
69+
while other capsules vendor just a single shared source package.
70+
71+
### Source repo - monorepo
72+
73+
The source repo holds the canonical code. A single workflow template triggers
74+
the dispatch chain on every release.
75+
76+
```
77+
demo-syncweaver-source/
78+
├── .github/
79+
│ └── workflows/
80+
│ └── syncweaver-source-dispatch.yml ← notifies orchestrator on release
81+
└── modules/
82+
└── hello/ ← vendored into host as code/hello
83+
├── DESCRIPTION
84+
├── NAMESPACE
85+
├── R/
86+
├── inst/
87+
└── man/
88+
```
89+
90+
### Host repo - Code Ocean capsule
91+
92+
The host repo consumes vendored code and carries a lockfile that pins each
93+
dependency to a specific ref and git SHA.
94+
95+
```
96+
demo-syncweaver-host/
97+
├── .github/
98+
│ └── workflows/
99+
│ ├── syncweaver-host-update.yml ← receives dispatch, opens update PR
100+
│ └── syncweaver-host-contribute-patch.yml ← sends local patches upstream
101+
├── .syncweaver-lock.json ← pins source repos + refs
102+
└── code/
103+
├── main.R
104+
├── hello/ ← vendored from demo-syncweaver-source modules/hello
105+
│ ├── DESCRIPTION
106+
│ ├── NAMESPACE
107+
│ ├── R/
108+
│ └── inst/
109+
└── MOSuite/ ← vendored from CCBR/MOSuite
110+
```
111+
112+
### Source repo - MOSuite
113+
114+
This is a package-style source repository. The canonical implementation lives in
115+
the package root, and the syncweaver source-dispatch workflow is defined under
116+
`.github/workflows/`.
117+
118+
```
119+
multiOmicsSuite/
120+
├── .github/
121+
│ └── workflows/
122+
│ └── syncweaver-source-dispatch.yml ← notifies syncweaver on release
123+
├── DESCRIPTION
124+
├── NAMESPACE
125+
├── R/ ← primary package implementation
126+
│ ├── cli.R
127+
│ ├── clean.R
128+
│ ├── differential.R
129+
│ ├── normalize.R
130+
│ └── ...
131+
├── inst/
132+
│ ├── extdata/
133+
│ └── quarto/
134+
├── man/
135+
└── tests/
136+
```
137+
138+
### Host repo example - MOSuite-create capsule
139+
140+
This host repo is a Code Ocean capsule. It vendors source code into `code/`,
141+
tracks upstream state in `.syncweaver-lock.json`, and keeps capsule runtime
142+
files alongside the vendored package.
143+
144+
```
145+
MOSuite-create/
146+
├── .github/
147+
│ └── workflows/
148+
│ └── syncweaver-update-source.yml ← host-side sync workflow in this repo
149+
├── .syncweaver-lock.json ← pins vendored sources to refs + SHAs
150+
├── code/
151+
│ ├── main.R
152+
│ ├── run/
153+
│ └── MOSuite/ ← vendored from multiOmicsSuite
154+
├── environment/
155+
│ ├── Dockerfile
156+
│ └── postInstall
157+
├── metadata/
158+
│ └── metadata.yml
159+
└── tests/
160+
```
161+
162+
## Repos
163+
164+
| Role | Example repo | Key file |
165+
|------|-------------|----------|
166+
| Source | [demo-syncweaver-source](https://github.com/NIDAP-Community/demo-syncweaver-source) | `.github/workflows/syncweaver-source-dispatch.yml` |
167+
| Host | [demo-syncweaver-host](https://github.com/NIDAP-Community/demo-syncweaver-host) | `.syncweaver-lock.json`, `.github/workflows/syncweaver-host-update.yml` |
168+
| Orchestrator | [CCBR/syncweaver](https://github.com/CCBR/syncweaver) | `.github/host-repositories.yml`, `.github/workflows/syncweaver-update-hosts` |
169+
170+
## Lockfile
171+
172+
The host repo tracks each vendored dependency in `.syncweaver-lock.json`:
173+
174+
```json
175+
{
176+
"sources": {
177+
"code/hello": {
178+
"repo_url": "https://github.com/NIDAP-Community/demo-syncweaver-source",
179+
"ref": "main",
180+
"remote_subdir": "modules/hello"
181+
}
182+
}
183+
}
184+
```
185+
186+
When the source repo publishes a release, the dispatch chain updates the
187+
vendored code at `code/hello` and opens a pull request in the host repo.

0 commit comments

Comments
 (0)