# Tinyforge Codemaps — Index

**Last Updated:** 2026-05-16

This directory contains architectural maps of key Tinyforge subsystems. Each codemap focuses on one major area: core data types, contract surfaces, integration points, and recipes for extending the system.

## Codemaps

| Area | File | Focus |
|------|------|-------|
| **Workload Plugin** | [`workload-plugin.md`](./workload-plugin.md) | Source × Trigger plugin contracts; registry lookups; webhook fan-out; how to add new kinds |

## Cross-References

- **Workload Refactor Handoff** — [`docs/WORKLOAD_REFACTOR_TODO.md`](../WORKLOAD_REFACTOR_TODO.md) — Full status of the trigger-split, legacy cutover, and remaining Priority items
- **Webhook Documentation** — [`docs/webhooks.md`](../webhooks.md) — Outgoing webhook events, signature scheme, receiver code samples
- **Observability + Event Triggers** — [`docs/LOGSCAN_AND_TRIGGERS_TODO.md`](../LOGSCAN_AND_TRIGGERS_TODO.md) — Log scanning rules, event triggers, related infrastructure

## How to Use These Codemaps

1. **Starting a new feature** in an existing area? Read the relevant codemap first to understand the contract surface and integration seams.
2. **Adding a new plugin kind** (Source or Trigger)? See the recipes in [`workload-plugin.md`](./workload-plugin.md) — "How to Add a New Source Kind" / "How to Add a New Trigger Kind".
3. **Debugging a plugin dispatch failure** (deploy, webhook, reconcile)? The "Data Flow" and "Integration Points" sections map out each path end-to-end.
4. **Reviewing someone else's plugin PR**? Check the contracts (`Source.Deploy()`, `Trigger.Match()`, etc.) against the descriptions here.

## Coverage

These codemaps are automatically generated from the codebase structure. If a key file or area is missing, it indicates:

- The area is under active refactor (see [`WORKLOAD_REFACTOR_TODO.md`](../WORKLOAD_REFACTOR_TODO.md) for priority order)
- The area is legacy code scheduled for deprecation
- The area is simple enough to document inline (JSDoc + comments in the source)

## Freshness

Codemaps are updated whenever:
- A new plugin kind is added
- The contract surface changes (new Source/Trigger method, new Deps field, etc.)
- Integration points shift (new API endpoint, new reconciler behavior, etc.)
- A major refactor lands (see workload-refactor status for examples)

When you land a change that affects these areas, please update the relevant codemap and the `Last Updated` timestamp.