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