frontend-patterns/README.md

# frontend-patterns

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 v0.1 research scaffold with evidence collection still pending. 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.


## Research entry point

Start with the [research program](research/plan/ResearchProgram.md), its
[protocol](research/plan/ResearchProtocol.md) and [validation cases](research/plan/ValidationCases.md).
The first cycle is ready in [FEP-WP-0002](workplans/FEP-WP-0002-seed-language-validation.md):
resolve the metadata contract, review contrasting sources and test a connected seed
corpus. Later phases broaden coverage and evaluate retrieval against real systems.

The [research bench](research/bench/README.md) now provides executable source
investigations through infospace-bench. Run `make bench-test` to verify the adapter
and `make bench-plan` to inspect the synthetic pilot. Real source review is pending.