Files
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

439 lines
8.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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