From 65bdf3da732710cb70794f84138f128e99d7605e Mon Sep 17 00:00:00 2001 From: Eduardo Flores Date: Sat, 18 Jul 2026 23:32:45 -0600 Subject: [PATCH] docs(forge): define concept taxonomy --- AGENTS.md | 4 +++- README.md | 42 ++++++++++++++++++------------------ docs/concepts.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 22 deletions(-) create mode 100644 docs/concepts.md diff --git a/AGENTS.md b/AGENTS.md index c8e7f4b..acef904 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,9 @@ Forge is a multilingual engineering lab organized by technology concepts, not programming languages. -- Keep every experiment self-contained, including its dependencies, commands, and context. +- Keep every experiment self-contained, including its dependencies, commands, and context, and follow the [experiment README guideline](docs/experiment-readme-guideline.md) for its documentation. +- Before creating a top-level concept directory, follow the [concept guidelines](docs/concepts.md): reuse an existing concept when it fits, and create one only for a meaningfully distinct engineering focus. +- Update the root README experiment table whenever adding a new experiment or repository; keep the `Experiment` and `Purpose` columns, and insert the row alphabetically by concept, then by experiment name within a repeated concept. - Write technical artifacts in English unless an experiment explicitly requires another language. - Keep documentation and tests with the behavior they describe. - Preserve focused scope; do not expand one experiment into unrelated repository-wide infrastructure. diff --git a/README.md b/README.md index 953be5e..90e9dae 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# forge +# ⚒️ forge A space for experimenting with emerging standards, architectures, and engineering concepts. @@ -6,24 +6,24 @@ Here, ideas are tested through working software: assumptions are challenged, tra ## Experiments -New experiments should follow the [experiment README guideline](docs/experiment-readme-guideline.md) so their intent, execution, and verification remain useful to both humans and agents. +Use the [concept guidelines](docs/concepts.md) to place experiments by engineering question. New experiments should also follow the [experiment README guideline](docs/experiment-readme-guideline.md) so their intent, execution, and verification remain useful to both humans and agents. -| Experiment | Status | Purpose | -| --- | --- | --- | -| [HTTP QUERY / Node.js + Fastify](http-query-rfc/node-fastify/) | Active experiment | Explore body-bearing HTTP QUERY requests with Fastify. | -| [Declarative desktop UI / Qt Quick + PySide6](declarative-desktop-ui/qt-quick/python-pyside6/) | Migrated snapshot | Compare a QML view with a minimal Python bootstrap. | -| [Event-driven desktop UI / Qt Widgets + PySide6](event-driven-desktop-ui/qt-widgets/python-pyside6/) | Migrated snapshot | Demonstrate widget composition and signal-slot interaction. | -| [Batch processing / Spring Batch log aggregation](batch-processing/log-aggregation/java-spring-batch/) | Migrated snapshot | Import CSV log records through a chunk-oriented batch job. | -| [Database sharding / order service with Spring and ShardingSphere](database-sharding/order-service/java-spring-shardingsphere/) | Migrated snapshot | Route orders across two MySQL databases by order ID parity. | -| [API client CLI / TMDB + Cobra](api-client-cli/tmdb/go-cobra/) | Migrated snapshot | Explore a typed API client behind a Cobra command interface. | -| [API wrapper / cached weather + `net/http`](api-wrapper/cached-weather/go-net-http/) | Migrated snapshot | Wrap a weather API with Redis caching and per-IP rate limiting. | -| [REST API / routing CRUD with Chi](rest-api/routing-crud/go-chi/) | Migrated snapshot | Explore resource-oriented routing while proxying CRUD requests. | -| [Content management / Markdown notes with SQLite](content-management/markdown-notes/go-sqlite/) | Migrated snapshot | Persist notes behind a repository boundary with a framework-free client. | -| [In-memory storage / HTTP key-value store](in-memory-storage/key-value-store/go-http/) | Migrated snapshot | Expose a concurrent map through HTTP with Prometheus instrumentation. | -| [Numeric precision / money with decimal libraries](numeric-precision/money/go-decimal/) | Migrated snapshot | Compare floating-point pitfalls with rational and decimal representations. | -| [Batch processing / generic jobs with GoBatch](batch-processing/generic-jobs/go-gobatch/) | Archived learning | Preserve a parked reader-processor-writer and partitioning proof of concept. | -| [Web framework basics / Express Hello World](web-framework-basics/hello-world/node-express/) | Migrated snapshot | Demonstrate the minimum Express route and server lifecycle. | -| [Application scaffolding / Express Generator](application-scaffolding/express-generator/node-express/) | Migrated snapshot | Record the conventional routers, views, middleware, and error boundaries generated for Express. | -| [REST API / TODO service with Express and Sequelize](rest-api/todo-service/node-express-sequelize/) | Migrated snapshot | Separate routing, controllers, and PostgreSQL persistence in a small task service. | -| [REST API / DNF history with FastAPI](rest-api/system-history/python-fastapi/) | Migrated snapshot | Parse local DNF transaction history through an asynchronous HTTP endpoint. | -| [Web framework basics / FastAPI request validation](web-framework-basics/request-validation/python-fastapi/) | Migrated snapshot | Demonstrate typed path, query, and body validation with FastAPI and Pydantic. | +| Experiment | Purpose | +| --- | --- | +| [API client CLI / TMDB + Cobra](api-client-cli/tmdb/go-cobra/) | Explore a typed API client behind a Cobra command interface. | +| [API wrapper / cached weather + `net/http`](api-wrapper/cached-weather/go-net-http/) | Wrap a weather API with Redis caching and per-IP rate limiting. | +| [Application scaffolding / Express Generator](application-scaffolding/express-generator/node-express/) | Record the conventional routers, views, middleware, and error boundaries generated for Express. | +| [Batch processing / generic jobs with GoBatch](batch-processing/generic-jobs/go-gobatch/) | Preserve a parked reader-processor-writer and partitioning proof of concept. | +| [Batch processing / Spring Batch log aggregation](batch-processing/log-aggregation/java-spring-batch/) | Import CSV log records through a chunk-oriented batch job. | +| [Content management / Markdown notes with SQLite](content-management/markdown-notes/go-sqlite/) | Persist notes behind a repository boundary with a framework-free client. | +| [Database sharding / order service with Spring and ShardingSphere](database-sharding/order-service/java-spring-shardingsphere/) | Route orders across two MySQL databases by order ID parity. | +| [Declarative desktop UI / Qt Quick + PySide6](declarative-desktop-ui/qt-quick/python-pyside6/) | Compare a QML view with a minimal Python bootstrap. | +| [Event-driven desktop UI / Qt Widgets + PySide6](event-driven-desktop-ui/qt-widgets/python-pyside6/) | Demonstrate widget composition and signal-slot interaction. | +| [HTTP QUERY / Node.js + Fastify](http-query-rfc/node-fastify/) | Explore body-bearing HTTP QUERY requests with Fastify. | +| [In-memory storage / HTTP key-value store](in-memory-storage/key-value-store/go-http/) | Expose a concurrent map through HTTP with Prometheus instrumentation. | +| [Numeric precision / money with decimal libraries](numeric-precision/money/go-decimal/) | Compare floating-point pitfalls with rational and decimal representations. | +| [REST API / DNF history with FastAPI](rest-api/system-history/python-fastapi/) | Parse local DNF transaction history through an asynchronous HTTP endpoint. | +| [REST API / routing CRUD with Chi](rest-api/routing-crud/go-chi/) | Explore resource-oriented routing while proxying CRUD requests. | +| [REST API / TODO service with Express and Sequelize](rest-api/todo-service/node-express-sequelize/) | Separate routing, controllers, and PostgreSQL persistence in a small task service. | +| [Web framework basics / Express Hello World](web-framework-basics/hello-world/node-express/) | Demonstrate the minimum Express route and server lifecycle. | +| [Web framework basics / FastAPI request validation](web-framework-basics/request-validation/python-fastapi/) | Demonstrate typed path, query, and body validation with FastAPI and Pydantic. | diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000..d4e776e --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,56 @@ +# Forge concept guidelines + +Use concepts to group experiments by the primary engineering question they investigate. The hierarchy is concept first, experiment second, and language or runtime implementation last. + +A concept is not a language, framework, business domain, delivery shape, or repository of origin. Those details describe how an experiment is implemented or delivered, not why it exists. + +## Placement process + +1. Identify the experiment's primary hypothesis or engineering question. +2. Compare that question with the admission boundaries and exclusions below. +3. Reuse an existing concept when its boundary fits, even if the technology or delivery shape differs. +4. Do not classify by language, framework, API style, executable type, or source repository. +5. If no existing concept fits, propose a new concept instead of creating it immediately. +6. Explain the proposed name, admission boundary, exclusions, why existing concepts do not fit, and which future experiments could reuse it. +7. Wait for explicit approval before updating the taxonomy or creating its directory. +8. After placement is approved, add or update the experiment record in the root [experiment table](../README.md#experiments). + +## Target taxonomy + +The taxonomy reflects current experiment evidence. It can evolve when new experiments expose a genuinely distinct engineering concern; it is not an immutable list. + +| Concept | Admit when the primary question is about | Exclude when the primary question is about | Current experiments | +| --- | --- | --- | --- | +| `application-boundaries` | Application bootstrap, layering, or responsibility and dependency boundaries. | Protocol semantics or storage algorithms. | [Express Hello World](../web-framework-basics/hello-world/node-express/), [Express Generator](../application-scaffolding/express-generator/node-express/), [Markdown notes](../content-management/markdown-notes/go-sqlite/), [TODO service](../rest-api/todo-service/node-express-sequelize/) | +| `batch-processing` | Staged jobs, chunks, partitioning, or execution metadata. | Request-response APIs or general application layering without a batch lifecycle. | [GoBatch generic jobs](../batch-processing/generic-jobs/go-gobatch/), [Spring Batch log aggregation](../batch-processing/log-aggregation/java-spring-batch/) | +| `desktop-ui-architecture` | Desktop UI composition, responsibility boundaries, or event flow. | Web delivery or non-UI application structure. | [Qt Quick](../declarative-desktop-ui/qt-quick/python-pyside6/), [Qt Widgets](../event-driven-desktop-ui/qt-widgets/python-pyside6/) | +| `external-service-integration` | Consuming, adapting, caching, rate-limiting, or otherwise protecting access to an upstream service. | HTTP behavior owned by the local service or storage as the primary concern. | [TMDB client CLI](../api-client-cli/tmdb/go-cobra/), [cached weather](../api-wrapper/cached-weather/go-net-http/) | +| `http-semantics-and-contracts` | HTTP method semantics, routing, request validation, representations, or API contracts. | General application layering, upstream adaptation, or storage internals. | [HTTP QUERY](../http-query-rfc/node-fastify/), [Chi routing CRUD/proxy](../rest-api/routing-crud/go-chi/), [DNF history](../rest-api/system-history/python-fastapi/), [FastAPI validation](../web-framework-basics/request-validation/python-fastapi/) | +| `storage-architecture` | Storage semantics, topology, concurrency, or partitioning where storage itself is the primary subject. | Persistence used only as an implementation detail behind application boundaries. | [in-memory key-value store](../in-memory-storage/key-value-store/go-http/), [database sharding](../database-sharding/order-service/java-spring-shardingsphere/) | +| `numeric-precision` | Numeric representation, arithmetic correctness, rounding, or precision tradeoffs. | Domain modeling where numeric behavior is incidental. | [money representations](../numeric-precision/money/go-decimal/) | + +## When to create a new concept + +Create one only when every statement is true: + +- [ ] No existing admission boundary describes the primary hypothesis. +- [ ] The distinction is an engineering concern, not an implementation or packaging detail. +- [ ] The name would remain useful across languages, frameworks, domains, and repository sources. +- [ ] Another experiment could plausibly investigate the same concern. +- [ ] The boundary and exclusions can be stated clearly. + +If any statement is false, reuse the closest existing concept and clarify the experiment name or README instead. + +## Classification anti-patterns + +| Avoid | Why | +| --- | --- | +| `rest-api` | Describes a delivery or interface style; classify the underlying question, such as HTTP contracts or application boundaries. | +| `web-framework-basics` | Groups by implementation context instead of the engineering concern. | +| Language buckets such as `go` or `python` | Languages belong at the implementation level. | +| Framework names such as `express` or `fastapi` | Frameworks are tools used to test a hypothesis, not durable concepts. | +| Business-domain-only buckets such as `weather` or `content-management` | Domains provide examples but do not define the reusable engineering question. | + +## Migration status + +Current directory paths remain unchanged for now. This guide defines the target classification model; any directory move requires a separate reviewed change that updates affected links and automation.