From 2a5dabdc858e6ec0138d9e03e84319dc7ed80f77 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 24 Sep 2026 07:55:34 +0200 Subject: [PATCH] Preserve initial frontend pattern language research scaffold Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9 --- README.md | 84 +++- TREE.md | 69 +++ architectures/DocumentWeb.md | 18 + architectures/Islands.md | 18 + architectures/LocalFirst.md | 18 + architectures/Microfrontends.md | 18 + architectures/README.md | 24 ++ architectures/SPA.md | 18 + architectures/ServerComponents.md | 18 + canon/Forces.md | 80 ++++ canon/FrontendPatternLanguage.md | 219 ++++++++++ canon/PatternSchema.md | 96 +++++ canon/Relations.md | 71 ++++ canon/Responsibilities.md | 49 +++ canon/Scales.md | 89 ++++ patterns/README.md | 104 +++++ patterns/address/README.md | 7 + patterns/affordance/README.md | 7 + patterns/authority/README.md | 7 + patterns/composition/README.md | 7 + patterns/execution/README.md | 7 + patterns/mutation/README.md | 7 + patterns/projection/README.md | 7 + patterns/quality/README.md | 7 + patterns/synchronization/README.md | 7 + research/README.md | 18 + .../CarniatoGrandUnifyingArchitecture.md | 79 ++++ research/catalog/PatternCandidateCatalog.md | 24 ++ research/catalog/SourceCatalog.md | 31 ++ .../FrontendArchitectureCompendium.md | 31 ++ research/concepts/GenerativeSequence.md | 42 ++ research/concepts/ResponsibilityModel.md | 42 ++ research/plan/OpenQuestions.md | 28 ++ research/plan/ResearchProgram.md | 395 ++++++++++++++++++ sequences/CollaborativeApplication.md | 15 + sequences/ContentSite.md | 15 + sequences/GeneralWebApplication.md | 112 +++++ sequences/LocalFirstApplication.md | 15 + sequences/README.md | 23 + sequences/TransactionalApplication.md | 15 + technologies/README.md | 17 + templates/Pattern.md | 56 +++ templates/TechnologyMapping.md | 17 + 43 files changed, 2030 insertions(+), 1 deletion(-) create mode 100644 TREE.md create mode 100644 architectures/DocumentWeb.md create mode 100644 architectures/Islands.md create mode 100644 architectures/LocalFirst.md create mode 100644 architectures/Microfrontends.md create mode 100644 architectures/README.md create mode 100644 architectures/SPA.md create mode 100644 architectures/ServerComponents.md create mode 100644 canon/Forces.md create mode 100644 canon/FrontendPatternLanguage.md create mode 100644 canon/PatternSchema.md create mode 100644 canon/Relations.md create mode 100644 canon/Responsibilities.md create mode 100644 canon/Scales.md create mode 100644 patterns/README.md create mode 100644 patterns/address/README.md create mode 100644 patterns/affordance/README.md create mode 100644 patterns/authority/README.md create mode 100644 patterns/composition/README.md create mode 100644 patterns/execution/README.md create mode 100644 patterns/mutation/README.md create mode 100644 patterns/projection/README.md create mode 100644 patterns/quality/README.md create mode 100644 patterns/synchronization/README.md create mode 100644 research/README.md create mode 100644 research/cases/CarniatoGrandUnifyingArchitecture.md create mode 100644 research/catalog/PatternCandidateCatalog.md create mode 100644 research/catalog/SourceCatalog.md create mode 100644 research/compendium/FrontendArchitectureCompendium.md create mode 100644 research/concepts/GenerativeSequence.md create mode 100644 research/concepts/ResponsibilityModel.md create mode 100644 research/plan/OpenQuestions.md create mode 100644 research/plan/ResearchProgram.md create mode 100644 sequences/CollaborativeApplication.md create mode 100644 sequences/ContentSite.md create mode 100644 sequences/GeneralWebApplication.md create mode 100644 sequences/LocalFirstApplication.md create mode 100644 sequences/README.md create mode 100644 sequences/TransactionalApplication.md create mode 100644 technologies/README.md create mode 100644 templates/Pattern.md create mode 100644 templates/TechnologyMapping.md diff --git a/README.md b/README.md index 574d763..795148d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,85 @@ # frontend-patterns -A Christopher Alexander style pattern language for frontend architecture and design. \ No newline at end of file +A coherent, generative pattern language for frontend architecture and design. + +The project treats frontend architecture not as a choice among frameworks or named styles, but as the progressive resolution of recurring forces concerning: + +- authority, +- addressability, +- projection, +- interaction, +- mutation, +- synchronization and reconciliation, +- composition, +- execution and delivery, +- quality boundaries. + +The repository is intended as an **infospace for both human and agentic reference**. + +Its goal is to make frontend architecture: + +1. understandable as a set of recurring design problems, +2. navigable as a connected language of patterns, +3. generative rather than merely taxonomic, +4. explicit about trade-offs and failure modes, +5. independent of framework fashion, +6. grounded in known implementations and sources, +7. machine-readable enough for agents to reason over. + +## Core proposition + +> Frontend architecture is the progressive resolution of forces concerning +> authority, addressability, projection, interaction, synchronization, +> composition, and execution. A frontend pattern language captures recurring +> resolutions of those forces and the contexts they create for subsequent +> design decisions. + +## Repository map + +- `canon/` — normative vocabulary and structure of the language. +- `patterns/` — individual frontend architecture and design patterns. +- `sequences/` — generative sequences for common frontend situations. +- `architectures/` — named architectural configurations expressed through patterns. +- `technologies/` — mappings from technologies/frameworks to the patterns they implement. +- `research/` — research material, source reconciliation, concepts, catalogues, and cases. +- `templates/` — authoring templates for new patterns and mappings. + +## Design principles + +### Patterns before products + +React, Solid, HTMX, Astro, LiveView, Vue, Svelte and similar technologies are treated as implementations and examples, not as the ontology. + +### Forces before preferences + +A pattern should be selected because of the forces present in a context, not because a framework community considers it idiomatic. + +### Relations before lists + +Patterns form a graph. Important relations include: + +- requires +- enables +- refines +- generalizes +- complements +- alternative-to +- conflicts-with +- commonly-combined-with +- creates-context-for +- implemented-by +- observed-in + +### Sequences before checklists + +A pattern language should help generate architecture through an ordered sequence of decisions. + +### Failure modes are part of the pattern + +Software patterns must describe when they become harmful, misleading, expensive or fragile. + +## Status + +This repository begins as a research-backed v0.1 scaffold. The first research case is Ryan Carniato's +"The Grand Unifying Architecture of Frontend", used as a starting point for decomposing modern frontend +architectures into deeper responsibilities and forces. diff --git a/TREE.md b/TREE.md new file mode 100644 index 0000000..0553097 --- /dev/null +++ b/TREE.md @@ -0,0 +1,69 @@ +# Repository Tree + +```text +frontend-patterns/ +├── architectures/ +│ ├── DocumentWeb.md +│ ├── Islands.md +│ ├── LocalFirst.md +│ ├── Microfrontends.md +│ ├── README.md +│ ├── ServerComponents.md +│ └── SPA.md +├── canon/ +│ ├── Forces.md +│ ├── FrontendPatternLanguage.md +│ ├── PatternSchema.md +│ ├── Relations.md +│ ├── Responsibilities.md +│ └── Scales.md +├── patterns/ +│ ├── address/ +│ │ └── README.md +│ ├── affordance/ +│ │ └── README.md +│ ├── authority/ +│ │ └── README.md +│ ├── composition/ +│ │ └── README.md +│ ├── execution/ +│ │ └── README.md +│ ├── mutation/ +│ │ └── README.md +│ ├── projection/ +│ │ └── README.md +│ ├── quality/ +│ │ └── README.md +│ ├── synchronization/ +│ │ └── README.md +│ └── README.md +├── research/ +│ ├── cases/ +│ │ └── CarniatoGrandUnifyingArchitecture.md +│ ├── catalog/ +│ │ ├── PatternCandidateCatalog.md +│ │ └── SourceCatalog.md +│ ├── compendium/ +│ │ └── FrontendArchitectureCompendium.md +│ ├── concepts/ +│ │ ├── GenerativeSequence.md +│ │ └── ResponsibilityModel.md +│ ├── plan/ +│ │ ├── OpenQuestions.md +│ │ └── ResearchProgram.md +│ └── README.md +├── sequences/ +│ ├── CollaborativeApplication.md +│ ├── ContentSite.md +│ ├── GeneralWebApplication.md +│ ├── LocalFirstApplication.md +│ ├── README.md +│ └── TransactionalApplication.md +├── technologies/ +│ └── README.md +├── templates/ +│ ├── Pattern.md +│ └── TechnologyMapping.md +├── INTENT.md +└── README.md +``` diff --git a/architectures/DocumentWeb.md b/architectures/DocumentWeb.md new file mode 100644 index 0000000..a16f7f5 --- /dev/null +++ b/architectures/DocumentWeb.md @@ -0,0 +1,18 @@ +# DocumentWeb + +Status: research stub + +## Intent + +Describe **DocumentWeb** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/architectures/Islands.md b/architectures/Islands.md new file mode 100644 index 0000000..81d4b0b --- /dev/null +++ b/architectures/Islands.md @@ -0,0 +1,18 @@ +# Islands + +Status: research stub + +## Intent + +Describe **Islands** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/architectures/LocalFirst.md b/architectures/LocalFirst.md new file mode 100644 index 0000000..f6a72ae --- /dev/null +++ b/architectures/LocalFirst.md @@ -0,0 +1,18 @@ +# LocalFirst + +Status: research stub + +## Intent + +Describe **LocalFirst** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/architectures/Microfrontends.md b/architectures/Microfrontends.md new file mode 100644 index 0000000..c0487ca --- /dev/null +++ b/architectures/Microfrontends.md @@ -0,0 +1,18 @@ +# Microfrontends + +Status: research stub + +## Intent + +Describe **Microfrontends** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/architectures/README.md b/architectures/README.md new file mode 100644 index 0000000..dc13f5a --- /dev/null +++ b/architectures/README.md @@ -0,0 +1,24 @@ +# Named Architectures + +Named frontend architectures are represented here as **configurations of patterns**. + +This prevents architectural labels from becoming indivisible categories. + +Initial candidates: + +- Document Web +- SPA +- Islands +- Server Components +- Microfrontends +- Local-First + +Each file should eventually answer: + +- What problem family does the architecture address? +- Which patterns are essential? +- Which are optional? +- Which forces make the configuration attractive? +- Which forces make it unattractive? +- Which architectural variants exist? +- Which technologies commonly implement it? diff --git a/architectures/SPA.md b/architectures/SPA.md new file mode 100644 index 0000000..e02dac3 --- /dev/null +++ b/architectures/SPA.md @@ -0,0 +1,18 @@ +# SPA + +Status: research stub + +## Intent + +Describe **SPA** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/architectures/ServerComponents.md b/architectures/ServerComponents.md new file mode 100644 index 0000000..2f30096 --- /dev/null +++ b/architectures/ServerComponents.md @@ -0,0 +1,18 @@ +# ServerComponents + +Status: research stub + +## Intent + +Describe **ServerComponents** as a configuration of independent frontend patterns rather than as a monolithic architectural style. + +## To establish + +- context +- dominant forces +- pattern configuration +- variants +- consequences +- failure modes +- known implementations +- sources diff --git a/canon/Forces.md b/canon/Forces.md new file mode 100644 index 0000000..c4068de --- /dev/null +++ b/canon/Forces.md @@ -0,0 +1,80 @@ +# Forces + +Forces make architectural decisions non-trivial. + +The initial force vocabulary is intentionally broader than frontend implementation concerns. + +## Experience + +- interaction latency +- perceived responsiveness +- continuity of interaction +- discoverability +- addressability +- accessibility +- recoverability +- offline usability + +## Information + +- authoritative consistency +- freshness +- cacheability +- conflict probability +- collaborative concurrency +- data locality +- privacy +- information completeness + +## Execution + +- first-content latency +- hydration cost +- client compute cost +- server compute cost +- bandwidth cost +- connection lifetime +- network reliability +- startup cost +- incremental update cost + +## Change + +- feature change frequency +- schema change frequency +- independent deployability +- team autonomy +- release coupling +- compatibility pressure + +## Engineering + +- implementation complexity +- reconciliation complexity +- cognitive load +- testability +- observability +- debuggability +- portability +- security exposure + +## Operations + +- scalability +- fault containment +- deployment complexity +- cache invalidation complexity +- telemetry quality +- incident recoverability + +## Research questions + +The vocabulary should remain small enough to reason with. + +Research should determine: + +- which forces are independent, +- which are merely metrics, +- which are compound concepts, +- which forces recur across most frontend patterns, +- which forces should be modeled as dimensions rather than labels. diff --git a/canon/FrontendPatternLanguage.md b/canon/FrontendPatternLanguage.md new file mode 100644 index 0000000..881ada9 --- /dev/null +++ b/canon/FrontendPatternLanguage.md @@ -0,0 +1,219 @@ +# Frontend Pattern Language + +## 1. Premise + +Frontend architecture is best understood as a progression of design decisions made under interacting forces. + +Frameworks and named architectural styles are downstream manifestations of these decisions. + +The pattern language therefore models: + +1. the **context** in which a problem occurs, +2. the **forces** that make the problem non-trivial, +3. the **pattern** that resolves those forces, +4. the **resulting context** created by the resolution, +5. the **relations** to other patterns, +6. the **known implementations** of the pattern. + +## 2. Fundamental responsibilities + +The initial model uses the following responsibilities. + +### Address + +How application state, resources, views or intents are named and revisited. + +Examples: + +- URL, +- route, +- document identifier, +- workspace identifier, +- command target. + +### Authority + +Which copy or system is allowed to define truth. + +Examples: + +- server authority, +- local authority, +- replicated authority, +- event-log authority. + +### Projection + +How authoritative or selected information becomes perceivable frontend state. + +Examples: + +- server-rendered HTML, +- client-rendered view, +- streamed projection, +- static projection. + +### Affordance + +Immediate local state and behavior that makes interaction responsive and intelligible. + +Examples: + +- open/closed state, +- focus state, +- draft input, +- pending feedback, +- speculative UI. + +### Mutation + +How user intent becomes a proposed or committed state change. + +### Synchronization + +How separated copies discover and exchange changes. + +### Reconciliation + +How conflicting, stale or concurrent observations and mutations are resolved. + +### Composition + +How independently understandable pieces combine into a larger frontend. + +### Execution + +Where and when computation occurs. + +Examples: + +- build time, +- server, +- edge, +- browser, +- worker, +- device. + +## 3. Relation to the Navigation → Content → Affordance model + +The useful decomposition proposed by Ryan Carniato can be interpreted as: + +```text +Navigation ≈ Address + mutation orchestration +Content ≈ Authority → Projection +Affordance ≈ local interaction + speculative state +``` + +This is a powerful projection for server-authoritative web applications. + +The broader language keeps authority independent so that local-first, peer-to-peer and replicated architectures can be represented without distortion. + +## 4. Pattern families + +Initial families: + +- `authority` +- `address` +- `projection` +- `affordance` +- `mutation` +- `synchronization` +- `composition` +- `execution` +- `quality` + +Families are navigational aids, not the primary ontology. + +Patterns may participate in several families. + +## 5. Pattern scales + +The initial scale model is: + +```text +L0 Experience / Product +L1 Application Topology +L2 Authority & Distribution +L3 Navigation & Projection +L4 Feature / Domain Boundaries +L5 Components +L6 Interaction & State +L7 Elements / Implementation +``` + +The scale prevents unlike patterns from being compared as peers. + +## 6. Generative use + +The language should support a sequence such as: + +```text +1. Characterize the experience +2. Place authority +3. Establish addressability +4. Place projection +5. Choose communication window +6. Add local affordances +7. Define mutation and reconciliation +8. Establish feature boundaries +9. Establish deployment boundaries +10. Strengthen quality boundaries +11. Measure and adapt +``` + +This sequence is provisional and must be tested against real systems. + +## 7. Technology mappings + +Technologies should be described as pattern configurations. + +Example: + +```text +Astro + implements: + Static Projection + Server Projection + Islands of Interactivity + Deferred Client Execution +``` + +A framework may implement several alternative patterns depending on configuration. + +## 8. Named architectures + +A named architecture is treated as a reusable configuration of patterns, not as an indivisible pattern. + +Examples: + +- SPA +- Islands +- Server Components +- Microfrontends +- Local-first +- Document web +- Hypermedia-driven application + +## 9. Evidence maturity + +Every pattern should eventually carry an evidence maturity. + +Suggested levels: + +- `hypothesis` +- `emerging` +- `established` +- `canonical` + +Maturity describes confidence in the pattern description, not desirability. + +## 10. Canon evolution + +Changes to the core canon should prefer: + +1. extending terminology, +2. clarifying relations, +3. introducing specializations, +4. only then redefining existing concepts. + +The objective is a stable conceptual core with an expanding edge. diff --git a/canon/PatternSchema.md b/canon/PatternSchema.md new file mode 100644 index 0000000..c20e57a --- /dev/null +++ b/canon/PatternSchema.md @@ -0,0 +1,96 @@ +# Pattern Schema + +Each pattern consists of structured metadata plus explanatory prose. + +## Canonical metadata + +```yaml +--- +id: FEP-AFF-001 +name: Optimistic Overlay +family: + - affordance + - mutation +scale: L6 +status: hypothesis + +context: + - remote authority + - perceptible mutation latency + +forces: + improves: + - interaction_latency + - perceived_responsiveness + worsens: + - reconciliation_complexity + - implementation_complexity + +requires: + - identifiable_mutation + - authoritative_state + +relations: + refines: + - local_interaction_state + enables: + - immediate_feedback + conflicts_with: + - destructive_uncompensated_mutation + +known_uses: [] + +evidence: + maturity: hypothesis + sources: [] +--- +``` + +## Human-readable structure + +Every pattern should contain: + +```text +# Pattern Name + +## Context + +## Problem + +## Forces + +## Solution + +## Dynamics + +## Resulting Context + +## Consequences + +## Failure Modes + +## Known Uses + +## Related Patterns + +## Evidence + +## Implementation Notes +``` + +## Requirements + +A pattern should: + +- describe a recurring problem, +- expose at least two meaningful forces, +- propose a reusable configuration, +- explain consequences, +- identify failure modes, +- create or refine a context in which other patterns apply. + +A useful technique is not automatically a pattern. + +A framework feature is not automatically a pattern. + +A pattern name should identify a reusable architectural idea rather than a product-specific API. diff --git a/canon/Relations.md b/canon/Relations.md new file mode 100644 index 0000000..f7672b0 --- /dev/null +++ b/canon/Relations.md @@ -0,0 +1,71 @@ +# Pattern Relations + +The language is primarily a graph. + +## Core relations + +### requires + +Pattern A depends on the presence of Pattern B or on the context created by B. + +### enables + +Applying A makes B possible or substantially easier. + +### creates-context-for + +A changes the system such that B becomes a relevant subsequent decision. + +This is especially important for generative sequences. + +### refines + +A is a more specific realization of B. + +### generalizes + +A captures the common structure of several more specific patterns. + +### complements + +A and B solve different parts of a larger problem and commonly reinforce each other. + +### alternative-to + +A and B address substantially the same problem using different trade-offs. + +### conflicts-with + +The assumptions or consequences of A and B are structurally incompatible or create severe tension. + +### commonly-combined-with + +Empirical relation based on frequent co-occurrence. + +### implemented-by + +Links a pattern to technologies or concrete mechanisms. + +### observed-in + +Links a pattern to known systems or architectures. + +## Relation semantics + +Relations should be directional where possible. + +For example: + +```text +Server Authority + creates-context-for → Server Projection +``` + +is more informative than: + +```text +Server Authority + related-to ↔ Server Projection +``` + +Avoid a generic `related-to` relation unless no stronger relation can be justified. diff --git a/canon/Responsibilities.md b/canon/Responsibilities.md new file mode 100644 index 0000000..8445cca --- /dev/null +++ b/canon/Responsibilities.md @@ -0,0 +1,49 @@ +# Responsibilities + +This document defines the current responsibility model used to analyze frontend architectures. + +## Address + +Names or locates application state, resources, views and intents. + +## Authority + +Determines which actor or replica may establish truth. + +## Projection + +Transforms selected state into perceivable representation. + +## Affordance + +Provides the local state and behavior necessary for immediate interaction. + +## Mutation + +Carries user intent toward state change. + +## Synchronization + +Propagates state or change between separated actors. + +## Reconciliation + +Resolves divergence, conflict, stale state or concurrency. + +## Composition + +Combines independently understandable frontend structures. + +## Execution + +Places computation in time and location. + +## Important qualification + +These responsibilities are analytical dimensions, not necessarily software components. + +One module may implement several responsibilities. + +One responsibility may be distributed across many modules. + +The model should therefore not be turned into a mandatory component architecture. diff --git a/canon/Scales.md b/canon/Scales.md new file mode 100644 index 0000000..94d445e --- /dev/null +++ b/canon/Scales.md @@ -0,0 +1,89 @@ +# Scales + +Patterns operate at different architectural scales. + +## L0 — Experience / Product + +Concerns the overall interactive system experienced by a user. + +Examples: + +- collaborative editor, +- transactional workflow, +- content publication, +- offline field application. + +## L1 — Application Topology + +Large-scale application organization. + +Examples: + +- independently deployable frontend, +- application shell, +- frontend/backend partitioning. + +## L2 — Authority & Distribution + +Placement and replication of authoritative state. + +Examples: + +- server authority, +- local authority, +- replicated authority. + +## L3 — Navigation & Projection + +Addressability, routing, rendering and delivery of perceivable state. + +Examples: + +- URL as state, +- server projection, +- client projection, +- streaming projection. + +## L4 — Feature / Domain Boundaries + +Functional decomposition. + +Examples: + +- vertical feature slice, +- bounded frontend feature, +- backend for frontend. + +## L5 — Components + +Reusable interaction and presentation structures. + +Examples: + +- presentation model, +- compound component, +- controlled component. + +## L6 — Interaction & State + +Fine-grained interaction behavior. + +Examples: + +- local interaction state, +- optimistic overlay, +- pending state. + +## L7 — Elements / Implementation + +Low-level implementation structures. + +Examples: + +- lazy boundary, +- error boundary, +- focus restoration. + +## Rule + +Patterns from different scales may relate strongly, but should not be treated as equivalent alternatives merely because they are all called "frontend patterns". diff --git a/patterns/README.md b/patterns/README.md new file mode 100644 index 0000000..ce810e5 --- /dev/null +++ b/patterns/README.md @@ -0,0 +1,104 @@ +# Patterns + +This directory contains canonical frontend patterns. + +Each pattern should conform to `canon/PatternSchema.md`. + +## Initial families + +- `authority/` +- `address/` +- `projection/` +- `affordance/` +- `mutation/` +- `synchronization/` +- `composition/` +- `execution/` +- `quality/` + +## Candidate seed patterns + +### Authority + +- Server Authority +- Local Authority +- Replicated Authority +- Event-Log Authority +- Single Writer +- Derived State + +### Address + +- URL as Application State +- Resource Address +- Hierarchical Route +- Progressive Navigation + +### Projection + +- Static Projection +- Server Projection +- Client Projection +- Hybrid Projection +- Streaming Projection +- Islands of Interactivity +- Server Components +- Progressive Hydration +- Resumable UI + +### Affordance + +- Local Interaction State +- Immediate Feedback +- Pending State +- Optimistic Overlay +- Undoable Intent +- Speculative Interaction + +### Mutation & Synchronization + +- Command Mutation +- Form Mutation +- Idempotent Mutation +- Invalidate and Reproject +- Pull Synchronization +- Push Synchronization +- Persistent Subscription +- Conflict-Free Merge +- Explicit Conflict + +### Composition + +- Presentation / Domain Separation +- Presentation Model +- Vertical Feature Slice +- Public Module Surface +- Independent Feature Boundary +- Microfrontend +- Backend for Frontend +- Design System + +### Execution + +- Build-Time Execution +- Server Execution +- Edge Execution +- Client Execution +- Deferred Execution +- Code Split +- Lazy Load +- Independent Deployment + +### Quality + +- Progressive Enhancement +- Accessible by Construction +- Failure Boundary +- Async Boundary +- Security Boundary +- Privacy Boundary +- Performance Budget +- Observable Interaction +- Recoverable Interaction + +These names are candidates. Research should consolidate, rename, split or reject them as needed. diff --git a/patterns/address/README.md b/patterns/address/README.md new file mode 100644 index 0000000..552ad22 --- /dev/null +++ b/patterns/address/README.md @@ -0,0 +1,7 @@ +# Address Patterns + +Candidate and canonical patterns concerning **address**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/affordance/README.md b/patterns/affordance/README.md new file mode 100644 index 0000000..e5fa4f3 --- /dev/null +++ b/patterns/affordance/README.md @@ -0,0 +1,7 @@ +# Affordance Patterns + +Candidate and canonical patterns concerning **affordance**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/authority/README.md b/patterns/authority/README.md new file mode 100644 index 0000000..089045f --- /dev/null +++ b/patterns/authority/README.md @@ -0,0 +1,7 @@ +# Authority Patterns + +Candidate and canonical patterns concerning **authority**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/composition/README.md b/patterns/composition/README.md new file mode 100644 index 0000000..b9c2930 --- /dev/null +++ b/patterns/composition/README.md @@ -0,0 +1,7 @@ +# Composition Patterns + +Candidate and canonical patterns concerning **composition**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/execution/README.md b/patterns/execution/README.md new file mode 100644 index 0000000..17db18e --- /dev/null +++ b/patterns/execution/README.md @@ -0,0 +1,7 @@ +# Execution Patterns + +Candidate and canonical patterns concerning **execution**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/mutation/README.md b/patterns/mutation/README.md new file mode 100644 index 0000000..c3f2cb5 --- /dev/null +++ b/patterns/mutation/README.md @@ -0,0 +1,7 @@ +# Mutation Patterns + +Candidate and canonical patterns concerning **mutation**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/projection/README.md b/patterns/projection/README.md new file mode 100644 index 0000000..86ae472 --- /dev/null +++ b/patterns/projection/README.md @@ -0,0 +1,7 @@ +# Projection Patterns + +Candidate and canonical patterns concerning **projection**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/quality/README.md b/patterns/quality/README.md new file mode 100644 index 0000000..22a0474 --- /dev/null +++ b/patterns/quality/README.md @@ -0,0 +1,7 @@ +# Quality Patterns + +Candidate and canonical patterns concerning **quality**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/patterns/synchronization/README.md b/patterns/synchronization/README.md new file mode 100644 index 0000000..5090126 --- /dev/null +++ b/patterns/synchronization/README.md @@ -0,0 +1,7 @@ +# Synchronization Patterns + +Candidate and canonical patterns concerning **synchronization**. + +Patterns in this directory should conform to `../../canon/PatternSchema.md`. + +This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata. diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..bff4f74 --- /dev/null +++ b/research/README.md @@ -0,0 +1,18 @@ +# Research + +Research material supports the canon but is kept separate from canonical patterns. + +The structure follows the C3 research deliverable model where useful: + +- `catalog/` — normalized inventories and indices. +- `compendium/` — explanatory synthesis of established knowledge. +- `concepts/` — emerging models and hypotheses. + +Additional directories: + +- `cases/` — focused analysis of articles, systems or architectural schools. +- `plan/` — research program, methods and open questions. + +Research material may be provisional. + +Promotion into the canon should happen only after the concept has been reconciled with competing models and tested against multiple frontend architectures. diff --git a/research/cases/CarniatoGrandUnifyingArchitecture.md b/research/cases/CarniatoGrandUnifyingArchitecture.md new file mode 100644 index 0000000..63bea27 --- /dev/null +++ b/research/cases/CarniatoGrandUnifyingArchitecture.md @@ -0,0 +1,79 @@ +# Case Study — The Grand Unifying Architecture of Frontend + +Status: initial research stub + +Source: +Ryan Carniato, "The Grand Unifying Architecture of Frontend". + +## Why this source matters + +The article attempts to unify several modern frontend architectures beneath framework-specific terminology. + +Its most useful conceptual move is the decomposition: + +```text +Navigation → Content → Affordance +``` + +with a characteristic movement: + +```text +client → server → client +``` + +for server-authoritative applications. + +## Initial interpretation + +### Navigation + +Contains aspects of: + +- addressability, +- routing, +- user intent, +- mutation initiation. + +### Content + +Contains aspects of: + +- authority, +- server-side state, +- projection. + +### Affordance + +Contains aspects of: + +- local interaction state, +- speculative state, +- immediate feedback. + +## Main qualification + +The model strongly fits server-authoritative web applications. + +It should not be promoted unchanged into the general canon because: + +- local-first systems may treat local data as primary, +- replicated systems may have multiple authorities, +- peer-to-peer systems may lack a distinguished server, +- microfrontend concerns cut across this axis, +- internal modularity is largely orthogonal to it. + +## Research tasks + +- extract concrete architecture examples from the article, +- identify all implicit assumptions, +- map each example to responsibility dimensions, +- identify candidate patterns, +- compare against: + - local-first, + - HTMX/hypermedia, + - SPA, + - server components, + - islands, + - LiveView-style persistent server interaction, +- identify where the model is descriptive versus normative, +- determine which concepts should enter the canon. diff --git a/research/catalog/PatternCandidateCatalog.md b/research/catalog/PatternCandidateCatalog.md new file mode 100644 index 0000000..59d7679 --- /dev/null +++ b/research/catalog/PatternCandidateCatalog.md @@ -0,0 +1,24 @@ +# Pattern Candidate Catalog + +This file tracks concepts before promotion into canonical pattern files. + +| Candidate | Family | Scale | Status | Main force | +|---|---|---:|---|---| +| Server Authority | authority | L2 | seed | authoritative consistency | +| Local Authority | authority | L2 | seed | offline usability | +| Replicated Authority | authority | L2 | seed | collaborative concurrency | +| URL as Application State | address | L3 | seed | addressability | +| Server Projection | projection | L3 | seed | client compute / delivery | +| Client Projection | projection | L3 | seed | interaction locality | +| Streaming Projection | projection | L3 | seed | first-content latency | +| Islands of Interactivity | projection | L3 | seed | client execution cost | +| Local Interaction State | affordance | L6 | seed | responsiveness | +| Optimistic Overlay | affordance | L6 | seed | interaction latency | +| Invalidate and Reproject | synchronization | L3/L6 | seed | freshness | +| Persistent Subscription | synchronization | L3 | seed | update latency | +| Vertical Feature Slice | composition | L4 | seed | change locality | +| Independent Feature Boundary | composition | L4 | seed | team autonomy | +| Progressive Enhancement | quality | cross-scale | seed | resilience/accessibility | +| Failure Boundary | quality | L5/L6 | seed | fault containment | + +`seed` means "worth researching", not "accepted into the canon". diff --git a/research/catalog/SourceCatalog.md b/research/catalog/SourceCatalog.md new file mode 100644 index 0000000..131c295 --- /dev/null +++ b/research/catalog/SourceCatalog.md @@ -0,0 +1,31 @@ +# Source Catalog + +Initial source families to populate. + +| Family | Representative sources | Research purpose | +|---|---|---| +| Pattern languages | Christopher Alexander, Hillside/PLoP literature | Pattern form, relations, generative sequences | +| GUI architecture | Martin Fowler, MVC/MVP/Presentation Model | Presentation/domain/state separation | +| Unidirectional state | Flux, Redux, Elm | State transition and dependency direction | +| Hypermedia | REST, HTML forms, HTMX | Navigation, mutation, server projection | +| Rendering | web.dev, framework docs, Patterns.dev | CSR/SSR/SSG/hydration/islands/streaming | +| Local-first | Ink & Switch and related work | Local authority, sync, conflict handling | +| Distributed state | CRDT/event sourcing/sync literature | Reconciliation and replication | +| Modularity | Feature-Sliced Design | Feature boundaries and dependency rules | +| Organizational architecture | Microfrontend literature | Independent ownership/deployment | +| Quality | WCAG, progressive enhancement, web performance | Cross-cutting architectural forces | + +## Catalog policy + +Each source should eventually capture: + +- source identity, +- date/version, +- scope, +- vocabulary used, +- candidate patterns, +- dominant forces, +- assumptions, +- contradictions, +- known implementations, +- evidence quality. diff --git a/research/compendium/FrontendArchitectureCompendium.md b/research/compendium/FrontendArchitectureCompendium.md new file mode 100644 index 0000000..cd92511 --- /dev/null +++ b/research/compendium/FrontendArchitectureCompendium.md @@ -0,0 +1,31 @@ +# Frontend Architecture Compendium + +## Purpose + +Provide a continuously improving synthesis of the major ideas used to reason about frontend architecture. + +The compendium explains schools of thought without treating any one of them as the canonical model. + +## Initial chapters + +1. From GUI architecture to web architecture +2. Navigation and the document web +3. Client/server authority +4. State management and unidirectional flow +5. Rendering and projection +6. Hydration, islands and resumability +7. Server components and streamed UI +8. Hypermedia-driven applications +9. Local-first and replicated frontends +10. Composition and feature slicing +11. Microfrontends and organizational boundaries +12. Accessibility, resilience and progressive enhancement +13. Performance as architecture +14. Frontend observability and recoverability +15. Pattern languages as a unifying representation + +## Editorial rule + +The compendium may explain technologies and historical movements in detail. + +Canonical patterns should remain technology-independent whenever possible. diff --git a/research/concepts/GenerativeSequence.md b/research/concepts/GenerativeSequence.md new file mode 100644 index 0000000..b247993 --- /dev/null +++ b/research/concepts/GenerativeSequence.md @@ -0,0 +1,42 @@ +# Concept — Generative Frontend Architecture Sequence + +Status: hypothesis + +## Candidate sequence + +```text +Characterize Experience +→ Place Authority +→ Establish Addressability +→ Place Projection +→ Choose Communication Window +→ Add Local Affordances +→ Define Mutation & Reconciliation +→ Establish Feature Boundaries +→ Establish Deployment Boundaries +→ Strengthen Quality Boundaries +→ Measure & Adapt +``` + +## Hypothesis + +Ordering matters. + +For example: + +- authority influences synchronization, +- addressability influences navigation and projection, +- projection placement influences execution cost, +- local affordances influence mutation/reconciliation requirements, +- feature boundaries may later justify deployment boundaries. + +The language should capture these causal dependencies rather than present all patterns as an unordered menu. + +## Validation + +Test the sequence against contrasting frontend systems and record: + +- decisions that occur too early, +- missing decisions, +- unavoidable feedback loops, +- architecture types that require alternate branches. diff --git a/research/concepts/ResponsibilityModel.md b/research/concepts/ResponsibilityModel.md new file mode 100644 index 0000000..4c7da4e --- /dev/null +++ b/research/concepts/ResponsibilityModel.md @@ -0,0 +1,42 @@ +# Concept — Frontend Responsibility Model + +Status: hypothesis + +## Proposition + +Frontend architectures can be usefully analyzed through nine responsibilities: + +1. Address +2. Authority +3. Projection +4. Affordance +5. Mutation +6. Synchronization +7. Reconciliation +8. Composition +9. Execution + +These are dimensions of responsibility, not mandatory modules. + +## Value + +The model appears broad enough to describe: + +- document-oriented web applications, +- SPAs, +- server-rendered systems, +- islands, +- server components, +- microfrontends, +- offline-first applications, +- local-first applications, +- collaborative replicated applications. + +## Research burden + +The model must be challenged for: + +- redundancy, +- missing responsibilities, +- ambiguous boundaries, +- inability to distinguish materially different architectures. diff --git a/research/plan/OpenQuestions.md b/research/plan/OpenQuestions.md new file mode 100644 index 0000000..452eb25 --- /dev/null +++ b/research/plan/OpenQuestions.md @@ -0,0 +1,28 @@ +# Open Questions + +## Core ontology + +- Is `Authority → Projection → Affordance` a better primary axis than traditional "state management" terminology? +- Should `Mutation` represent intent, transport, state transition, or be split? +- Is `Reconciliation` independent enough to be a first-class responsibility? +- Should `Communication Window` become a canonical dimension? + +## Pattern language + +- What qualifies as a pattern rather than a technique? +- How much implementation detail belongs in canonical patterns? +- How do we represent patterns that only make sense at one scale? +- How should pattern relations be validated? + +## Agentic use + +- Which metadata is necessary for useful pattern retrieval? +- Should the pattern graph be exported as JSON/YAML/RDF? +- Can force matching be made quantitative without creating false precision? +- Can architecture review be expressed as unresolved-force detection? + +## Evidence + +- What makes a frontend pattern "established"? +- Should known uses be manually curated or automatically mined? +- How should contradictory source claims be represented? diff --git a/research/plan/ResearchProgram.md b/research/plan/ResearchProgram.md new file mode 100644 index 0000000..45565e8 --- /dev/null +++ b/research/plan/ResearchProgram.md @@ -0,0 +1,395 @@ +# Frontend Patterns Research Program + +## 1. Objective + +Develop a coherent Alexander-style pattern language for frontend architecture and design that is useful to both human practitioners and software agents. + +The work should move from source collection toward: + +1. common vocabulary, +2. recurring forces, +3. candidate patterns, +4. pattern relations, +5. generative sequences, +6. architecture decompositions, +7. technology mappings, +8. machine-readable retrieval and reasoning. + +## 2. Research thesis + +Frontend architecture is not fundamentally organized around frameworks. + +It is organized around recurring decisions concerning: + +- authority, +- addressability, +- projection, +- interaction, +- mutation, +- synchronization, +- reconciliation, +- composition, +- execution, +- quality boundaries. + +Named architectures and frameworks are configurations or implementations of these decisions. + +## 3. First research case + +Use Ryan Carniato's "The Grand Unifying Architecture of Frontend" as the first extraction exercise. + +Research tasks: + +1. reconstruct its Navigation → Content → Affordance model, +2. identify implicit assumptions, +3. extract candidate patterns, +4. identify the forces each pattern resolves, +5. identify where server-authority assumptions cease to hold, +6. compare against local-first architectures, +7. compare against hypermedia architectures, +8. compare against SPA and server-component architectures, +9. map findings into the responsibility model, +10. retain useful concepts without treating the article as the canonical ontology. + +## 4. Research streams + +### Stream A — Historical GUI architecture + +Study: + +- MVC, +- MVP, +- Presentation Model, +- Presentation / Domain Separation, +- Flux / Redux, +- Elm architecture, +- event-driven UI. + +Goal: + +Identify durable state, dependency and interaction patterns that predate current web frameworks. + +### Stream B — Web navigation and hypermedia + +Study: + +- document web, +- REST/hypermedia, +- progressive enhancement, +- HTML forms, +- HTMX-style server interaction, +- browser navigation semantics. + +Goal: + +Understand addressability, navigation, mutation and server projection. + +### Stream C — Rendering and execution + +Study: + +- CSR, +- SSR, +- SSG, +- hydration, +- partial hydration, +- islands, +- server components, +- resumability, +- streaming, +- edge execution. + +Goal: + +Separate projection patterns from execution placement and delivery mechanisms. + +### Stream D — State authority and synchronization + +Study: + +- client/server state, +- remote caches, +- optimistic UI, +- local-first, +- CRDTs, +- event sourcing, +- offline-first, +- subscriptions, +- push/pull synchronization. + +Goal: + +Establish a coherent authority/synchronization/reconciliation language. + +### Stream E — Composition and organizational architecture + +Study: + +- component composition, +- feature slicing, +- microfrontends, +- design systems, +- frontend platform architecture, +- backend-for-frontend patterns, +- monorepos and deployment independence. + +Goal: + +Separate software composition from ownership and deployment boundaries. + +### Stream F — Quality patterns + +Study: + +- accessibility, +- progressive enhancement, +- performance, +- fault containment, +- security, +- privacy, +- observability, +- recovery. + +Goal: + +Represent cross-cutting frontend qualities as architectural patterns and forces rather than afterthoughts. + +## 5. Research method + +For each source or architecture: + +### Step 1 — Extract claims + +Record what the source says without prematurely normalizing terminology. + +### Step 2 — Identify forces + +Ask what competing constraints make the proposed solution useful. + +### Step 3 — Extract candidate patterns + +Look for recurring configurations rather than named technologies. + +### Step 4 — Normalize vocabulary + +Map source-specific language into the current canon where possible. + +### Step 5 — Find counterexamples + +Test whether the pattern still holds under: + +- offline operation, +- local authority, +- real-time collaboration, +- very low interaction density, +- high interaction density, +- independent deployment, +- unreliable networks, +- strong accessibility requirements. + +### Step 6 — Establish relations + +Record: + +- requires, +- enables, +- refines, +- alternatives, +- conflicts, +- resulting contexts. + +### Step 7 — Test generativity + +Ask whether the pattern helps produce a next architectural decision. + +### Step 8 — Promote cautiously + +Move a concept into `patterns/` only when it is sufficiently stable and reusable. + +## 6. Initial source families + +Create a source catalog spanning: + +- Christopher Alexander and pattern-language literature, +- Martin Fowler GUI architecture, +- REST and hypermedia literature, +- Redux / Elm / Flux, +- Feature-Sliced Design, +- microfrontends, +- local-first, +- web.dev rendering literature, +- Patterns.dev, +- framework architectural documentation, +- accessibility and progressive-enhancement literature, +- distributed-systems synchronization concepts. + +## 7. Initial pattern extraction targets + +Priority candidate patterns: + +### Authority + +- Server Authority +- Local Authority +- Replicated Authority +- Derived State +- Single Writer + +### Address & navigation + +- URL as Application State +- Resource Address +- Hierarchical Route +- Progressive Navigation + +### Projection + +- Static Projection +- Server Projection +- Client Projection +- Streaming Projection +- Islands of Interactivity + +### Interaction + +- Local Interaction State +- Immediate Feedback +- Pending State +- Optimistic Overlay + +### Synchronization + +- Invalidate and Reproject +- Pull Synchronization +- Push Synchronization +- Persistent Subscription +- Conflict-Free Merge +- Explicit Conflict + +### Composition + +- Presentation / Domain Separation +- Vertical Feature Slice +- Independent Feature Boundary +- Backend for Frontend + +### Quality + +- Progressive Enhancement +- Failure Boundary +- Accessible by Construction +- Performance Budget +- Observable Interaction + +## 8. Validation architectures + +The emerging language should be tested against at least these application types: + +1. mostly-static publication, +2. e-commerce storefront, +3. administrative CRUD application, +4. high-interaction SaaS workspace, +5. real-time dashboard, +6. collaborative editor, +7. offline field application, +8. local-first personal tool, +9. large microfrontend estate, +10. mobile-web/PWA application. + +A useful language should explain all ten without forcing them into one preferred architecture. + +## 9. Agentic use cases + +The infospace should eventually support prompts such as: + +> Given this application description, identify the dominant forces and propose applicable patterns. + +> Explain why the current architecture exhibits this failure mode. + +> Which patterns are incompatible with our offline requirement? + +> Decompose this framework architecture into technology-independent patterns. + +> What pattern should be considered next after choosing server authority and streaming projection? + +> Compare two architectures in terms of forces, not framework features. + +This requires graph-friendly metadata and stable identifiers. + +## 10. Initial milestones + +### M0 — Scaffold + +- repository structure, +- intent, +- responsibility model, +- force vocabulary, +- relation vocabulary, +- pattern schema, +- research method. + +### M1 — Seed corpus + +- source catalog, +- Carniato case analysis, +- historical GUI architecture review, +- local-first review, +- rendering architecture review. + +### M2 — First canonical language + +- 20–30 candidate patterns, +- reviewed force vocabulary, +- relation graph, +- first architecture decompositions. + +### M3 — Generative sequences + +- general web application, +- content site, +- transactional application, +- collaborative application, +- local-first application. + +### M4 — Agentic reference surface + +- normalized metadata, +- stable identifiers, +- pattern graph export, +- query examples, +- retrieval/evaluation fixtures. + +### M5 — Empirical refinement + +- test language against real repositories, +- collect pattern co-occurrence, +- identify missing forces, +- identify misleading or redundant patterns, +- revise maturity levels. + +## 11. Open research questions + +1. Is the current responsibility model minimal? +2. Should mutation be separate from intent? +3. Is reconciliation a responsibility or a synchronization subfamily? +4. Is addressability a frontend responsibility or a system-level concern? +5. Should rendering and projection remain distinct terms? +6. How should temporal behavior be represented? +7. How should pattern strength or evidence be measured? +8. Can pattern selection be meaningfully represented as constraint solving? +9. How should anti-patterns be modeled? +10. Can architecture health be described as unresolved or contradictory forces? + +## 12. Definition of useful progress + +The project is not advanced by adding pattern names alone. + +Useful progress means improving one or more of: + +- conceptual precision, +- pattern reuse, +- relation quality, +- generative power, +- evidence quality, +- applicability across architectures, +- retrieval quality for humans and agents. diff --git a/sequences/CollaborativeApplication.md b/sequences/CollaborativeApplication.md new file mode 100644 index 0000000..eaa1dca --- /dev/null +++ b/sequences/CollaborativeApplication.md @@ -0,0 +1,15 @@ +# CollaborativeApplication + +Status: research stub + +A generative sequence for multi-user concurrent interaction, presence, synchronization and conflict resolution. + +## Research tasks + +- identify dominant forces, +- establish authority assumptions, +- determine suitable projection patterns, +- determine synchronization model, +- identify failure modes, +- derive candidate sequence, +- test against known implementations. diff --git a/sequences/ContentSite.md b/sequences/ContentSite.md new file mode 100644 index 0000000..9911929 --- /dev/null +++ b/sequences/ContentSite.md @@ -0,0 +1,15 @@ +# ContentSite + +Status: research stub + +A generative sequence optimized for content-oriented sites with strong addressability, delivery and progressive-enhancement requirements. + +## Research tasks + +- identify dominant forces, +- establish authority assumptions, +- determine suitable projection patterns, +- determine synchronization model, +- identify failure modes, +- derive candidate sequence, +- test against known implementations. diff --git a/sequences/GeneralWebApplication.md b/sequences/GeneralWebApplication.md new file mode 100644 index 0000000..6e970fd --- /dev/null +++ b/sequences/GeneralWebApplication.md @@ -0,0 +1,112 @@ +# General Web Application — Generative Sequence + +Status: hypothesis + +## Starting question + +How should a web application progressively resolve its frontend architecture without starting from a framework choice? + +## Sequence + +### 1. Characterize the experience + +Identify: + +- dominant user activities, +- interaction intensity, +- continuity requirements, +- collaboration requirements, +- offline requirements, +- addressability requirements, +- latency sensitivity. + +### 2. Place authority + +Choose among patterns such as: + +- Server Authority +- Local Authority +- Replicated Authority +- Event-Log Authority + +### 3. Establish addressability + +Determine what must be named, linked, revisited, bookmarked or shared. + +Potential patterns: + +- URL as Application State +- Resource Address +- Hierarchical Route + +### 4. Place projection + +Determine where perceivable state is derived. + +Potential patterns: + +- Static Projection +- Server Projection +- Client Projection +- Hybrid Projection +- Streaming Projection + +### 5. Choose the communication window + +Determine whether communication is: + +- request/response, +- polling, +- long-lived, +- streamed, +- replicated, +- peer-to-peer. + +### 6. Add local affordances + +Identify state that should remain near the user interaction. + +Potential patterns: + +- Local Interaction State +- Pending State +- Immediate Feedback +- Optimistic Overlay + +### 7. Define mutation and reconciliation + +Decide: + +- command shape, +- idempotency, +- conflict handling, +- invalidation, +- resynchronization. + +### 8. Establish feature boundaries + +Determine which domain and interaction capabilities can evolve independently. + +### 9. Establish deployment boundaries + +Only split independent deployment where the organizational and runtime forces justify it. + +### 10. Strengthen quality boundaries + +Apply accessibility, failure containment, security, privacy, observability and performance patterns. + +### 11. Measure and adapt + +Observe runtime behavior and revisit earlier choices when actual forces differ from assumed forces. + +## Research status + +This sequence must be tested against contrasting architectures: + +- content site, +- CRUD SaaS, +- real-time dashboard, +- collaborative editor, +- e-commerce storefront, +- local-first application, +- microfrontend estate. diff --git a/sequences/LocalFirstApplication.md b/sequences/LocalFirstApplication.md new file mode 100644 index 0000000..bcb5022 --- /dev/null +++ b/sequences/LocalFirstApplication.md @@ -0,0 +1,15 @@ +# LocalFirstApplication + +Status: research stub + +A generative sequence for applications in which local state remains usable and authoritative interaction continues despite network loss. + +## Research tasks + +- identify dominant forces, +- establish authority assumptions, +- determine suitable projection patterns, +- determine synchronization model, +- identify failure modes, +- derive candidate sequence, +- test against known implementations. diff --git a/sequences/README.md b/sequences/README.md new file mode 100644 index 0000000..7e6c4ed --- /dev/null +++ b/sequences/README.md @@ -0,0 +1,23 @@ +# Generative Sequences + +A sequence guides architecture construction through an ordered series of pattern decisions. + +Sequences are not mandatory reference architectures. + +They should explain: + +- starting context, +- major forces, +- ordering rationale, +- decision points, +- applicable patterns, +- branches, +- resulting contexts. + +Initial sequence candidates: + +- `GeneralWebApplication.md` +- `ContentSite.md` +- `TransactionalApplication.md` +- `CollaborativeApplication.md` +- `LocalFirstApplication.md` diff --git a/sequences/TransactionalApplication.md b/sequences/TransactionalApplication.md new file mode 100644 index 0000000..ab612ce --- /dev/null +++ b/sequences/TransactionalApplication.md @@ -0,0 +1,15 @@ +# TransactionalApplication + +Status: research stub + +A generative sequence for applications dominated by forms, workflows, commands, validation and authoritative transactions. + +## Research tasks + +- identify dominant forces, +- establish authority assumptions, +- determine suitable projection patterns, +- determine synchronization model, +- identify failure modes, +- derive candidate sequence, +- test against known implementations. diff --git a/technologies/README.md b/technologies/README.md new file mode 100644 index 0000000..e1027f4 --- /dev/null +++ b/technologies/README.md @@ -0,0 +1,17 @@ +# Technology Mappings + +Technologies are mapped to the patterns they can implement. + +Technology files are descriptive, not normative. + +A mapping may contain: + +- implemented patterns, +- optional patterns, +- constraints, +- characteristic defaults, +- architectural assumptions, +- counterexamples, +- source references. + +A technology must not become part of the core ontology merely because it is popular. diff --git a/templates/Pattern.md b/templates/Pattern.md new file mode 100644 index 0000000..e829761 --- /dev/null +++ b/templates/Pattern.md @@ -0,0 +1,56 @@ +--- +id: FEP-XXX-000 +name: Pattern Name +family: [] +scale: L0 +status: hypothesis + +context: [] + +forces: + improves: [] + worsens: [] + +requires: [] + +relations: + enables: [] + refines: [] + generalizes: [] + complements: [] + alternative-to: [] + conflicts-with: [] + creates-context-for: [] + +known_uses: [] + +evidence: + maturity: hypothesis + sources: [] +--- + +# Pattern Name + +## Context + +## Problem + +## Forces + +## Solution + +## Dynamics + +## Resulting Context + +## Consequences + +## Failure Modes + +## Known Uses + +## Related Patterns + +## Evidence + +## Implementation Notes diff --git a/templates/TechnologyMapping.md b/templates/TechnologyMapping.md new file mode 100644 index 0000000..b0b680d --- /dev/null +++ b/templates/TechnologyMapping.md @@ -0,0 +1,17 @@ +# Technology Name + +## Scope + +## Characteristic architectural assumptions + +## Implemented patterns + +## Optional patterns + +## Constraints + +## Known variants + +## Counterexamples + +## Sources