42 lines
4.4 KiB
Markdown
42 lines
4.4 KiB
Markdown
# GEWU architecture and engineering handbook
|
|
|
|
Started 12 October 2026; revised 13 October 2026. Architecture proposal v0.3. The initial local-agent instruction pack exists; service, connector and UI implementation has not started.
|
|
|
|
**Tagline:** Investigate. Connect. Remember.
|
|
|
|
GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Interpretations vary; the name evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse. GEWU is a shared research library with a read-only website and an MCP contribution workflow. The [goal](GOAL.md) and [PRD](PRD.md) own product requirements. This handbook translates them into a proposed implementation and working protocols. It does not change their priorities or claim that M0 is complete.
|
|
|
|
## Read in this order
|
|
|
|
1. [Reference review](reviews/ARCHITECTURE_REFERENCE_REVIEW.md): which practices to borrow, adapt or reject.
|
|
2. [Architecture](architecture/ARCHITECTURE.md): components, technology choices, alternatives and deployment.
|
|
3. [Acceptance and evidence contract](architecture/ACCEPTANCE_CONTRACT.md): records, authority, replay, crash recovery and source integrity.
|
|
4. [Development protocol](development/DEVELOPMENT_PROTOCOL.md): implementation workflow, module boundaries, verification and documentation.
|
|
5. [Visual design protocol](development/VISUAL_DESIGN_PROTOCOL.md): the owner-selected editorial research direction and its review gates.
|
|
6. [Agent and security protocol](development/AGENT_SECURITY_PROTOCOL.md): agent workflows, permissions, untrusted inputs and client acceptance.
|
|
7. [Operations protocol](development/OPERATIONS_PROTOCOL.md): persistence, deployment, backup, migration and incident response.
|
|
8. [Local agent](architecture/LOCAL_AGENT.md) and [source pack](../agents/gewu/README.md): RESEARCH-style workspace profile, modular skills and pipeline procedures.
|
|
9. [Module replacement protocol](development/MODULARITY_PROTOCOL.md): public contracts, dependency boundaries, replacement tests, state migration and rollback.
|
|
|
|
The [independent architecture review](reviews/ARCHITECTURE_SENIOR_REVIEW.md) records findings and corrections for the v0.2 acceptance foundation. The [local-agent and modularity addition](reviews/LOCAL_AGENT_MODULARITY_REVIEW.md) records the v0.3 scope and verification separately.
|
|
|
|
## Decision status
|
|
|
|
| Status | Meaning here |
|
|
| --- | --- |
|
|
| Product requirement | Already stated in GOAL/PRD; this proposal must satisfy it. |
|
|
| Owner-selected direction | Warm editorial research workspace, confirmed in this conversation. Exact tokens and layouts remain proposed. |
|
|
| Owner-required additions | Custom local agent in the RESEARCH workspace style; modular development across all components with tested replacement paths. |
|
|
| Architecture recommendation | Concrete engineering default for review; no implementation or measured acceptance implied. |
|
|
| Open owner decision | A policy, staffing, capacity or content choice that engineering cannot present as approved. |
|
|
|
|
Protocol language describes the intended implementation standard if this baseline is adopted. The reference projects' instructions have no authority over GEWU. Repository-specific Symbia consultations, agent-hook behavior, terminal aesthetics and approval requirements were reviewed as source material rather than activated.
|
|
|
|
## Next implementation boundary
|
|
|
|
Start with a disposable local vertical slice: upload an explicitly selected text/Markdown source through one client, create a shared source and project note, validate exact evidence and support records, automatically accept under a test policy, retrieve the committed revision, then open its citation in a read-only browser. Exercise both pilot projects and a retry/restart failure. The test policy is not the production policy.
|
|
|
|
Before that boundary becomes a pilot deployment, settle the open decisions listed in the architecture. Implementing a smaller slice does not reduce the PRD's full-v1 requirements for hybrid retrieval, supported source formats, four agent harnesses and portable operation.
|
|
|
|
Runtime versions will be pinned in lockfiles during scaffolding after compatibility checks. The agent pack has an instruction/version manifest, but there are no application dependency manifests, runnable service, browser implementation or deployment tests in this repository. Skill-file validation is separate from installed discovery and live workflow acceptance.
|