5.3 KiB
GEWU architecture and engineering handbook
Started 12 October 2026; revised 14 October 2026. Architecture proposal v0.3. The backend, authenticated HTTP/MCP workflows, a read-only research UI, and a modular GEWU agent pack are implemented to varying levels of local verification. Consult the implementation status and acceptance ledger for evidence and open gates.
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 and PRD 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
For a local setup and first browser session, start with the getting started guide. It uses a disposable synthetic registry and does not claim pilot qualification.
Start delivery planning with the implementation plan: work packages, pilot/full-v1 boundaries, decision gates and PRD traceability.
- Reference review: which practices to borrow, adapt or reject.
- Architecture: components, technology choices, alternatives and deployment.
- Acceptance and evidence contract: records, authority, replay, crash recovery and source integrity.
- Development protocol: implementation workflow, module boundaries, verification and documentation.
- Visual design protocol: the owner-selected editorial research direction and its review gates.
- Agent and security protocol: agent workflows, permissions, untrusted inputs and client acceptance.
- Operations protocol: persistence, deployment, backup, migration and incident response.
- Local agent and source pack: RESEARCH-style workspace profile, modular skills and pipeline procedures.
- Module replacement protocol: public contracts, dependency boundaries, replacement tests, state migration and rollback.
The independent architecture review records findings and corrections for the v0.2 acceptance foundation. The local-agent and modularity addition 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
The disposable local vertical slice now uploads a selected source through MCP, validates and accepts an evidence-backed note under a test policy, reads the committed revision, and opens its citation in the browser. Retry, recovery and scoped-read cases have local tests. The test policy is not the production policy. Remaining work includes real pilot source and question qualification, protected owner authorization, selected native-client workflows, portability and accessibility acceptance; see the implementation plan and ledger for the next gates.
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 are locked in the Python and web workspaces. The agent pack has a contract/version manifest, local checkpointing, and an additive installer; native-client discovery and workflow acceptance remain open. The service exposes authenticated reads and contribution workflows, and the browser reads accepted knowledge with citations. Pilot corpus evaluation, protected owner authorization, cross-platform qualification, deployment, and accessibility gates remain open. Skill-file validation is separate from installed discovery and live workflow acceptance.