Files
pages/docs/design/arch.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

8.3 KiB
Raw Permalink Blame History

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

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’.


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.

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. 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.
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.

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

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

GET /dev/api/auth
Accept-Language: ja-JP,ja;q=0.9,en;q=0.8

Canonical Identity Model

graph TD

DOMAIN[Domain UUID]
PATH[Semantic Path]
UUID[Page UUID]
REV[Revision]

DOMAIN --> PATH
PATH --> UUID
UUID --> REV

Important Principle

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

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

graph TD

PR[Principal]
CAP[Capabilities]

SP[Spot]
PAGE[Page]

PR --> CAP
CAP --> SP
SP --> PAGE

Example

Alice
 └─ auth-api:read

Spot:

Auth API
 └─ requires auth-api:read

Capability Evaluation

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

default deny
positive grants only

Macaroon Delegation

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
graph TD

SHARE["/s/abcdef"]

MAC[Anonymous Macaroon]

SP[Spot]
VIEW[Read-only Projection]

SHARE --> MAC
MAC --> SP
SP --> VIEW

Storage Model

graph TD

PAGE[Page UUID]
REV1[Revision 1]
REV2[Revision 2]
REV3[Revision 3]

PAGE --> REV1
PAGE --> REV2
PAGE --> REV3

Metadata is stored in the database. Immutable Document payloads use a global content-addressed filesystem:

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

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

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