Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
464 lines
9.9 KiB
Markdown
464 lines
9.9 KiB
Markdown
# Overview
|
||
|
||
## Concept
|
||
|
||
Pages Wiki is designed as **semantic locality driven knowledge system** rather than a traditional filesystem wiki.
|
||
|
||
### Key properties
|
||
|
||
- Hierarchy-oriented UI
|
||
- Graph-capable Internal model
|
||
- Language-neutral Semantic paths
|
||
- Capability-centric authorization
|
||
- Delegated access via macaroons xxx
|
||
|
||
## Implementation component names
|
||
|
||
The adopted subsystem names and boundaries are defined in
|
||
[Component names and responsibilities](ja/component-names.md).
|
||
Grammaratur owns document-format conversion and authoring fidelity, Dregarnuhr
|
||
owns in-process scheduling, and Geduldh owns immutable payload storage and bounded
|
||
materialization. Mestionora owns SQLite search/index projections with caller-supplied
|
||
read policies. Ordoschnellic owns bounded Web Push delivery and transport policy,
|
||
with recipient checks and transactional Inbox enqueue retained in the application.
|
||
Schutzaria evaluates trusted Path/locality/group/publication policy facts without I/O;
|
||
authentication, fact loading and transactional authority remain application-owned.
|
||
Kunstzeal owns built-in projection selection and bounded diagram-provider execution;
|
||
source authorization and sandbox delivery remain in the application.
|
||
Seheweit owns local resource collection and history-window/retention policy;
|
||
authorization, queue control and SQL persistence remain in the application.
|
||
All eight initial extractions preserve compatibility; their remaining capabilities
|
||
are tracked separately. These names do not rename Knowledge
|
||
City Model entities, public URIs, stored identifiers or deployment services.
|
||
|
||
## Knowledge City Model
|
||
|
||
Pages Wiki don’t only comprises Machine friendly but also Human-Facing friendly with Knowledge City Model.
|
||
|
||
Knowledge City Model constitute five administrative division unit called ‘domain’, ‘quartier’, ‘street’, ‘spot’, ‘page’.
|
||
|
||
- ‘page’ is minimal knowledge unit.
|
||
- ‘spot’ constitute multiple pages. Namely, spot is minimal knowledge group.
|
||
|
||
- An overgrown knowledge spot can’t be upgraded to a street.
|
||
- ‘zone’ is managed unit in data structure.
|
||
|
||
- ‘street’ is group of spot. ‘street’ used minimal knowledge city block.
|
||
|
||
- If existed mixed spot and various page, it is unconsolidated street.
|
||
- ‘quartier’ can be called if it consists of an aggregation of streets delineated through urban planning.
|
||
|
||
- An overgrown knowledge street can be upgraded to a quartier.
|
||
- ‘Domain’ is really site group. For example, ’Domain’ may indicate division and department group, project, and team. ‘Domain’ used as subdomain space in URI.
|
||
- ‘Domain’ managed by one ‘Campus’.
|
||
|
||
```mermaid
|
||
|
||
graph TD
|
||
Cm[Campus]
|
||
|
||
DmA[Domain: Sales Unit]
|
||
DmB[Domain: Technical Unit]
|
||
DmC[Domain: Management Unit]
|
||
|
||
%% Campus から Domain への接続
|
||
Cm-..->DmA
|
||
Cm-..->DmB
|
||
Cm-..->DmC
|
||
|
||
%% Zone定義(Quartier と Street を内包し、縦に並ぶよう調整)
|
||
subgraph Zone ["Zone"]
|
||
direction TB
|
||
|
||
%% Quartier レ法
|
||
QtA[Quartier: Network]
|
||
QtB[Quartier: Server]
|
||
QtC[Quartier: Application]
|
||
|
||
%% Street レ法
|
||
StA[Street: DNS]
|
||
StB[Street: Web]
|
||
StC[Street: Mail]
|
||
|
||
%% Zone内での上下関係を固定するための接続
|
||
QtB-->StA
|
||
QtB-->StB
|
||
StB-.if it is overgrown, upgrade to 'quartier'.->QtB
|
||
QtB-->StC
|
||
end
|
||
|
||
%% Domain から Zone(Quartier) への接続
|
||
DmB-->QtA
|
||
DmB-->QtB
|
||
DmB-->QtC
|
||
|
||
%% Zone(Street) から下位レイヤーへの接続
|
||
SpA[Spot: Web Infrastructure]
|
||
SpB[Spot: Wiki Application]
|
||
SpC[Spot: Search Engine]
|
||
|
||
StB-->SpA
|
||
StB-->SpB
|
||
StB-->SpC
|
||
|
||
%% Spot から Page への接続
|
||
PgA[Page: Access Control Model]
|
||
PgB[Page: Addressing Model]
|
||
PgC[Page: Authenticating Model]
|
||
|
||
SpB-->PgA
|
||
SpB-->PgB
|
||
SpB-->PgC
|
||
```
|
||
|
||
## Internal Semantic Structure
|
||
|
||
Pages Wiki is arranged by machine-friendly semantic structure.
|
||
|
||
The detailed responsibilities, invariants, schema, projections, API surface,
|
||
and implementation order for Quartier, Street, Spot, and MagicPage are defined
|
||
in [Knowledge City Model Detailed Design](knowledge-city-model.md).
|
||
|
||
Collaboration, notification, delegated sharing, extension providers, external
|
||
storage, malware inspection, controller DR, and multi-node HA must preserve
|
||
these identities through the contracts in
|
||
[Platform Extension Architecture](platform-extension-architecture.md). These
|
||
features extend Page/Revision/City projections; they do not introduce alternate
|
||
Page identity, mutable Revision payloads, or filesystem-style ownership.
|
||
|
||
- ‘ZoneTree’ is arranged tree-structured model for control ‘quartier’ and ‘street’, and so ‘spot’ as external pointer. ZoneTree referenced from domain.
|
||
- ‘SpotGraph’ is page pointer graph from spot.
|
||
|
||
- SpotGraph point page ID. Multiple spot can any page with page ID(called ‘MagicPage’).
|
||
- Revision
|
||
|
||
- A Page UUID owns an ordered Revision history.
|
||
- Each immutable Revision has a Revision UUID and references an immutable
|
||
Document by SHA-256.
|
||
- Revision identity and Document content identity are distinct.
|
||
- Revisions carry a BCP 47 language tag; `und` represents legacy or
|
||
language-unspecified content.
|
||
|
||
```mermaid
|
||
graph LR
|
||
|
||
Dm[Domain]
|
||
ZT[Zone Tree]
|
||
SG[Spot Graph]
|
||
PG[Pages]
|
||
RV[Revisions]
|
||
|
||
Dm--Domain refer to ZoneTree-->ZT
|
||
ZT--ZoneTree refer to spot with SpotGraph-->SG
|
||
SG--SpotGraph refer to page-->PG
|
||
PG--page refer to revisions-->RV
|
||
```
|
||
|
||
### MagicPage
|
||
|
||
The MagicPage can reach from multiple spot without depending quartier and street. So, A single Page may appear in multiple Spots.
|
||
|
||
This creates: rooted multitree
|
||
|
||
instead of strict filesystem hierarchy.
|
||
|
||
```mermaid
|
||
graph LR
|
||
|
||
SPA[Spot A]
|
||
SPB[Spot B]
|
||
SPC[Spot C]
|
||
|
||
P1[Page UUID=P1]
|
||
P2[Page UUID=P2]
|
||
|
||
SPA --> P1
|
||
SPB --> P1
|
||
SPC --> P2
|
||
```
|
||
|
||
## Language Projection Model
|
||
|
||
```mermaid
|
||
graph LR
|
||
|
||
REQ[Request]
|
||
AL[Accept-Language]
|
||
P[Page UUID]
|
||
|
||
JAJP[Revision ja-JP]
|
||
JA[Revision ja]
|
||
EN[Revision en]
|
||
|
||
REQ --> AL
|
||
AL --> P
|
||
|
||
P --> JAJP
|
||
JAJP -->|not found| JA
|
||
JA -->|not found| EN
|
||
```
|
||
|
||
### Example
|
||
|
||
```http
|
||
GET /dev/api/auth
|
||
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8
|
||
```
|
||
|
||
# Canonical Identity Model
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
DOMAIN[Domain UUID]
|
||
PATH[Semantic Path]
|
||
UUID[Page UUID]
|
||
REV[Revision]
|
||
|
||
DOMAIN --> PATH
|
||
PATH --> UUID
|
||
UUID --> REV
|
||
```
|
||
|
||
### Important Principle
|
||
|
||
```text
|
||
path != object
|
||
representation != object
|
||
(domain_uuid, path) = semantic address
|
||
object UUID = instance-global identity
|
||
```
|
||
|
||
A Domain owns a semantic path namespace, not the Page Object itself. The same
|
||
normalized path may exist in multiple Domains without conflict, and multiple
|
||
Domains may bind different paths to the same Page UUID. Cross-Domain links use
|
||
an absolute URL containing the destination FQDN. See
|
||
`domain-namespace-federation.md` for local/remote placement and Campus
|
||
authority modes.
|
||
|
||
## Authentication / Authorization Flow
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
OIDC[OIDC Provider]
|
||
PR[Principal]
|
||
MB[Membership]
|
||
RL[Role]
|
||
CAP[Capability Graph]
|
||
|
||
OIDC --> PR
|
||
PR --> MB
|
||
MB --> RL
|
||
RL --> CAP
|
||
```
|
||
|
||
### Important Separation
|
||
|
||
| Layer | Responsibility |
|
||
| --- | --- |
|
||
| OIDC | Identity proof |
|
||
| Principal | Canonical internal identity |
|
||
| Membership | Organizational mapping |
|
||
| Role | Semantic grouping |
|
||
| Capability | Actual authority |
|
||
|
||
## Capability Model
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
PR[Principal]
|
||
CAP[Capabilities]
|
||
|
||
SP[Spot]
|
||
PAGE[Page]
|
||
|
||
PR --> CAP
|
||
CAP --> SP
|
||
SP --> PAGE
|
||
```
|
||
|
||
## Example
|
||
|
||
```text
|
||
Alice
|
||
└─ auth-api:read
|
||
```
|
||
|
||
Spot:
|
||
|
||
```text
|
||
Auth API
|
||
└─ requires auth-api:read
|
||
```
|
||
|
||
## Capability Evaluation
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
REQ[Read Request]
|
||
PR[Principal]
|
||
SP[Spot]
|
||
CAP[Capability Check]
|
||
ALLOW[Allow]
|
||
DENY[Implicit Deny]
|
||
|
||
REQ --> PR
|
||
REQ --> SP
|
||
|
||
PR --> CAP
|
||
SP --> CAP
|
||
|
||
CAP -->|has capability| ALLOW
|
||
CAP -->|missing capability| DENY
|
||
```
|
||
|
||
### Important Principle
|
||
|
||
```text
|
||
default deny
|
||
positive grants only
|
||
```
|
||
|
||
## Macaroon Delegation
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
PR[Principal]
|
||
CAP[Capability]
|
||
|
||
MAC[Macaroon]
|
||
CAV[Caveats]
|
||
|
||
USR[Temporary User]
|
||
|
||
PR --> CAP
|
||
CAP --> MAC
|
||
MAC --> CAV
|
||
MAC --> USR
|
||
```
|
||
|
||
### Caveat Examples
|
||
|
||
- expires
|
||
- readonly
|
||
- network restriction
|
||
- lang restriction
|
||
- path restriction
|
||
|
||
## Share Link Model
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
SHARE["/s/abcdef"]
|
||
|
||
MAC[Anonymous Macaroon]
|
||
|
||
SP[Spot]
|
||
VIEW[Read-only Projection]
|
||
|
||
SHARE --> MAC
|
||
MAC --> SP
|
||
SP --> VIEW
|
||
```
|
||
|
||
## Storage Model
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
PAGE[Page UUID]
|
||
REV1[Revision 1]
|
||
REV2[Revision 2]
|
||
REV3[Revision 3]
|
||
|
||
PAGE --> REV1
|
||
PAGE --> REV2
|
||
PAGE --> REV3
|
||
```
|
||
|
||
The staged evolution to PostgreSQL/MySQL, Redis caches, S3 and network file
|
||
stores, together with backup/export/import and first-run setup, is defined in
|
||
[Storage Portability and Operations](storage-portability-and-operations.md).
|
||
The current supported runtime remains SQLite and local storage; the design
|
||
does not imply that remote backends are already selectable.
|
||
|
||
Metadata is stored in the database. Immutable Document payloads use a global
|
||
content-addressed filesystem:
|
||
|
||
```text
|
||
documents/
|
||
└─ sha256/
|
||
└─ ab/
|
||
└─ abcdef...
|
||
```
|
||
|
||
The payload extension is not used as identity. MIME type and canonical format
|
||
are metadata. A Revision row references the hash and never references a
|
||
mutable asset HEAD.
|
||
|
||
## Runtime Rendering Pipeline
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
REQ[HTTP Request]
|
||
|
||
PATH[Semantic Path]
|
||
UUID[Page UUID]
|
||
LANG[Language Resolution]
|
||
REV[Revision]
|
||
AUTH[Capability Evaluation]
|
||
RENDER[Render]
|
||
|
||
REQ --> PATH
|
||
PATH --> UUID
|
||
UUID --> LANG
|
||
LANG --> REV
|
||
REV --> AUTH
|
||
AUTH --> RENDER
|
||
```
|
||
|
||
## Overall Architectural Direction
|
||
|
||
```mermaid
|
||
graph TD
|
||
|
||
UI[Hierarchy UI]
|
||
TREE[Rooted Tree]
|
||
GRAPH[Semantic Graph]
|
||
UUID[UUID Identity]
|
||
LANG[Language Projection]
|
||
CAP[Capability Access]
|
||
MAC[Macaroon Delegation]
|
||
|
||
UI --> TREE
|
||
TREE --> GRAPH
|
||
GRAPH --> UUID
|
||
UUID --> LANG
|
||
LANG --> CAP
|
||
CAP --> MAC
|
||
```
|
||
|
||
## Final Summary
|
||
|
||
### Pages Wiki is:
|
||
|
||
- hierarchy-oriented for humans
|
||
- graph-capable internally
|
||
- semantic-locality-driven
|
||
- UUID identity based
|
||
- language-neutral
|
||
- capability-centric
|
||
- projection-oriented
|
||
|
||
### NOT:
|
||
|
||
- filesystem ACL centric
|
||
- path identity centric
|
||
- language hierarchy centric
|