Skip to content

Commit 883618a

Browse files
hta218hta218
committed
Add architecture overview and dependency resolution flow for Weaverse SDKs
1 parent 0ed2fa5 commit 883618a

1 file changed

Lines changed: 265 additions & 0 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# Weaverse SDKs Architecture Overview
2+
3+
| | |
4+
|---|---|
5+
| **Project** | Weaverse Headless CMS SDKs |
6+
| **Repository** | [github.com/Weaverse/weaverse](https://github.com/Weaverse/weaverse) |
7+
| **Version** | 5.10.0 (core packages) |
8+
| **License** | MIT |
9+
| **Status** | Active |
10+
| **Generated** | 2026-03-23 |
11+
| **Description** | Architecture diagrams and technical reference for the Weaverse SDKs monorepo, covering the layered package structure, dependency graph, build pipeline, state management flow, and deployment targets. |
12+
13+
```
14+
┌────────────────────────────────────────────────────────────────────────────────────┐
15+
│ APPLICATION LAYER (Framework Integrations) │
16+
├────────────────────────────────────────────────────────────────────────────────────┤
17+
│ │
18+
│ ┌──────────────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
19+
│ │ @weaverse/hydrogen │ │ @weaverse/next │ │ @weaverse/remix │ │
20+
│ │ (Shopify + RRv7) │ │ (Next.js) │ │ (Remix) │ │
21+
│ │ │ │ [Stub] │ │ [Stub] │ │
22+
│ │ WeaverseClient │ └──────────────────┘ └──────────────────┘ │
23+
│ │ WeaverseHydrogenRoot │ │
24+
│ │ Hydrogen-specific hooks │ │
25+
│ └────────────┬─────────────┘ │
26+
│ │ │
27+
└───────────────┼────────────────────────────────────────────────────────────────────┘
28+
│
29+
┌───────────────┼─────────────────────────────────────────────────────────────────────┐
30+
│ │ FRAMEWORK-SPECIFIC LAYER │
31+
├───────────────┼─────────────────────────────────────────────────────────────────────┤
32+
│ │ │
33+
│ ┌────────────▼────────────────┐ │
34+
│ │ @weaverse/react │ │
35+
│ │ (React bindings & hooks) │ │
36+
│ │ │ │
37+
│ │ - WeaverseContext │ │
38+
│ │ - useWeaverse() │ │
39+
│ │ - useItemInstance() │ │
40+
│ │ - useParentInstance() │ │
41+
│ │ - useChildInstances() │ │
42+
│ │ - WeaverseRenderer │ │
43+
│ │ │ │
44+
│ │ Deps: │ │
45+
│ │ └─ React >= 19 │ │
46+
│ │ └─ React Router >= 6 │ │
47+
│ │ └─ clsx (classname utils) │ │
48+
│ └────────────┬────────────────┘ │
49+
│ │ │
50+
└───────────────┼─────────────────────────────────────────────────────────────────────┘
51+
│
52+
┌───────────────┼──────────────────────────────────────────────────────────────────────┐
53+
│ │ CORE ABSTRACTION LAYER │
54+
├───────────────┼──────────────────────────────────────────────────────────────────────┤
55+
│ │ │
56+
│ ┌────────────▼─────────────────┐ │
57+
│ │ @weaverse/core │ │
58+
│ │ (Framework-agnostic base) │ │
59+
│ │ │ │
60+
│ │ - Weaverse (singleton) │ │
61+
│ │ - WeaverseItemStore │ │
62+
│ │ - ElementRegistry │ │
63+
│ │ - EventEmitter (pub/sub) │ │
64+
│ │ - Types & utilities │ │
65+
│ │ │ │
66+
│ │ NO external dependencies │ │
67+
│ └────────────┬─────────────────┘ │
68+
│ │ │
69+
└───────────────┼──────────────────────────────────────────────────────────────────────┘
70+
│
71+
┌───────────────┼───────────────────────────────────────────────────────────────────────┐
72+
│ │ SUPPORTING PACKAGES (Independent) │
73+
├───────────────┼───────────────────────────────────────────────────────────────────────┤
74+
│ │ │
75+
│ ┌────────────▼──────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
76+
│ │ @weaverse/schema (ESM) │ │ @weaverse/i18n │ │ @weaverse/cli │ │
77+
│ │ v0.8.2 (independent) │ │ v1.1.2 │ │ v5.5.2 │ │
78+
│ │ │ │ │ │ │ │
79+
│ │ Zod-based schemas │ │ i18n utilities │ │ Scaffold tools │ │
80+
│ │ Type validation │ │ i18next backend │ │ Project setup │ │
81+
│ │ Component definitions │ │ Waterfall │ │ Yargs CLI │ │
82+
│ │ │ │ fallback │ │ │ │
83+
│ └───────────────────────────┘ └──────────────────┘ └──────────────────┘ │
84+
│ │
85+
│ ┌──────────────────────────────────────┐ │
86+
│ │ @weaverse/biome (Config) │ │
87+
│ │ v5.7.3 │ │
88+
│ │ │ │
89+
│ │ Shared Biome configuration │ │
90+
│ │ - 2-space indentation │ │
91+
│ │ - Single quotes │ │
92+
│ │ - Prefers 'let' over 'const' │ │
93+
│ │ │ │
94+
│ └──────────────────────────────────────┘ │
95+
│ │
96+
└───────────────────────────────────────────────────────────────────────────────────────┘
97+
```
98+
99+
## Dependency Resolution Flow
100+
101+
```
102+
Application Event
103+
│
104+
▼
105+
┌──────────────────────┐
106+
│ @weaverse/hydrogen │ (Shopify Hydrogen integration)
107+
└──────────┬───────────┘
108+
│
109+
├─→ WeaverseClient (fetches data from Weaverse CMS)
110+
├─→ Registers components via ElementRegistry
111+
├─→ Renders via WeaverseRenderer
112+
│
113+
▼
114+
┌──────────────────────┐
115+
│ @weaverse/react │ (React context & hooks)
116+
└──────────┬───────────┘
117+
│
118+
├─→ useWeaverse() returns singleton instance
119+
├─→ useItemInstance() for component data
120+
├─→ useParentInstance() for parent access
121+
├─→ useChildInstances() for children access
122+
│
123+
▼
124+
┌──────────────────────┐
125+
│ @weaverse/core │ (Core state management)
126+
└──────────┬───────────┘
127+
│
128+
├─→ Weaverse (singleton pattern)
129+
│ └─→ itemInstances (Map)
130+
│ └─→ elementRegistry (Map)
131+
│ └─→ EventEmitter
132+
│
133+
├─→ WeaverseItemStore (extends EventEmitter)
134+
│ ├─→ Manages item data
135+
│ ├─→ Emits 'update' event on changes
136+
│ ├─→ Emits 'mounted' on DOM attachment
137+
│ └─→ Notifies parent/children
138+
│
139+
└─→ EventEmitter (pub/sub)
140+
├─→ on('update', callback)
141+
├─→ off(eventName, callback)
142+
└─→ emit(eventName, data)
143+
```
144+
145+
## Build & Deployment Pipeline
146+
147+
```
148+
MONOREPO ORCHESTRATION (Turbo v2.8.14)
149+
150+
Task Dependencies (turbo.json):
151+
- build: dependsOn=["^build"] → builds dependencies first
152+
- dev: dependsOn=["^build"] → dev watches with build cache
153+
- test: dependsOn=["^build"] → tests after build
154+
- typecheck: inputs=["packages/**/*.ts"] → checks all TS files
155+
156+
Command Flow:
157+
$ bun run build (orchestrated by Turbo)
158+
│
159+
├─→ @weaverse/core (no deps, builds first)
160+
├─→ @weaverse/schema (no deps)
161+
├─→ @weaverse/biome (no deps)
162+
├─→ @weaverse/i18n (no deps)
163+
│
164+
├─→ @weaverse/react (depends on core)
165+
├─→ @weaverse/cli (no deps)
166+
│
167+
└─→ @weaverse/hydrogen (depends on react + schema)
168+
└─→ @weaverse/next, @weaverse/remix (no deps)
169+
170+
Each Package Build (tsup):
171+
src/index.ts → [dist/index.js (CJS), dist/index.mjs (ESM)]
172+
→ dist/index.d.ts (TypeScript declarations)
173+
→ dist/index.*.map (source maps)
174+
```
175+
176+
## Code Quality Checks (Pre-commit & CI)
177+
178+
```
179+
1. Pre-commit Hook (Lefthook):
180+
- biome check --write (auto-fix staged files)
181+
- Auto-stage fixed files
182+
183+
2. GitHub Actions CI:
184+
- biome ci . (strict, no auto-fix)
185+
- bun run typecheck (TypeScript validation)
186+
187+
3. Quality Rules (Biome 2.4.4):
188+
✓ Single quotes only
189+
✓ 2-space indentation
190+
✓ No namespace imports (import * as)
191+
✓ Prefer let over const (useConst OFF)
192+
✓ Optional chaining (?.) required
193+
✓ No unused imports/variables
194+
✓ No console.* in production code
195+
```
196+
197+
## Release Process
198+
199+
```
200+
Trigger: "release [packages] as [major|minor|patch]"
201+
202+
Steps:
203+
1. Verify version bumps
204+
2. Bump package.json versions
205+
3. bun run build (rebuild with new versions)
206+
4. bun publish (publish to npm registry)
207+
5. Create git tag (v5.10.0, etc.)
208+
6. Create GitHub Release
209+
7. Sync development branch
210+
211+
Version Groups:
212+
- FIXED: core, react, hydrogen (sync versions: 5.10.0)
213+
- FREE: schema (0.8.2), cli (5.5.2), biome (5.7.3), i18n (1.1.2)
214+
```
215+
216+
## State Management Flow
217+
218+
```
219+
┌────────────────────────────────────┐
220+
│ Component Data Changes │
221+
│ (e.g., user updates color) │
222+
└─────────────┬──────────────────────┘
223+
│
224+
▼
225+
┌─────────────────┐
226+
│ WeaverseClient │ (Hydrogen)
227+
│ triggers update │
228+
└────────┬────────┘
229+
│
230+
▼
231+
┌──────────────────────────────┐
232+
│ WeaverseItemStore │ (Singleton instance)
233+
│ ._store = new data │
234+
│ .triggerUpdate() │
235+
└────────┬─────────────────────┘
236+
│
237+
├─→ emit('update')
238+
│
239+
▼
240+
┌──────────────────────────────┐
241+
│ React re-render │
242+
│ via useWeaverse() hooks │
243+
└────────┬─────────────────────┘
244+
│
245+
├─→ Child component data updates
246+
├─→ useItemInstance() reflects change
247+
├─→ useChildInstances() notified
248+
│
249+
▼
250+
┌──────────────────────────────┐
251+
│ DOM updates │
252+
│ (through React's rendering) │
253+
└──────────────────────────────┘
254+
```
255+
256+
## Deployment Targets
257+
258+
| Platform | Status | Notes |
259+
|----------|--------|-------|
260+
| Shopify Hydrogen (React Router v7) | **Primary** | Full support via `@weaverse/hydrogen` |
261+
| Next.js | Future/Stub | SSR/Static Generation |
262+
| Remix | Future/Stub | Server-side rendering |
263+
| Generic React Router v7 | Supported | Via `@weaverse/react` directly |
264+
265+
All packages deployed via npm under the `@weaverse` scope.

0 commit comments

Comments
 (0)