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.
439 lines
8.3 KiB
Markdown
439 lines
8.3 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
|
||
|
||
## 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
|