# Tags & Taxonomy (T&T) v2 – design

This branch implements a **proper tags and taxonomy** layer: controlled vocabulary, optional facets, and discovery (filter by tag).

## Goals

- **Controlled vocabulary** – Suggested or allowed terms so tags are consistent and filterable.
- **Facets (optional)** – Group terms by dimension (e.g. "Project type", "Platform", "Status").
- **Discovery** – Filter projects, guides, and frameworks by one or more tags.
- **New files** – T&T logic lives in `js/app-taxonomy.js` and `js/app-taxonomy-ui.js`; existing `app-tags.js` / `app-tags-ui.js` remain for storage and project/guide tag inputs.

## New files

| File | Purpose |
|------|--------|
| `js/app-taxonomy.js` | Vocabulary and facets (default set + API). Exposes `Blueprint.taxonomy`: getFacets(), getTermsForFacet(), getSuggestedTags(type), validateTag(). Later: load from DB or app_settings. |
| `js/app-taxonomy-ui.js` | Filter-by-tag UI: tag filter dropdown/chips for project list, guide list, or framework list; optional tag picker that suggests terms from taxonomy. |
| `docs/TAGS_TAXONOMY_V2.md` | This design. |

## Vocabulary (default)

Initial default vocabulary is in code (no DB yet). Example facets:

- **Project type:** `implementation`, `audit`, `demo`, `internal`, `documentation`
- **Platform:** `ga4`, `gtm`, `cross-domain`, `server-side`, `web`, `mobile`
- **Status:** `planning`, `implementation`, `live`, `audit`

Terms are shared across entity types; filtering can be "any tag" or per-facet later.

## API (app-taxonomy.js)

- `Blueprint.taxonomy.getFacets()` → `[{ id, label, terms: [] }]`
- `Blueprint.taxonomy.getTermsForFacet(facetId)` → `string[]`
- `Blueprint.taxonomy.getSuggestedTags(entityType)` → combined suggested list for autocomplete
- `Blueprint.taxonomy.validateTag(tag)` → boolean (optional; e.g. allow only suggested or allow any)
- Later: `Blueprint.taxonomy.loadFromServer()` if vocabulary is admin-managed.

## UI (app-taxonomy-ui.js)

- **Filter by tag** – When viewing project dropdown, guide list, or framework list: show a "Filter by tag" control (dropdown or chips). On change, filter the list to entities that have at least one of the selected tags.
- **Tag picker (optional)** – In project/guide tag input: suggest terms from `getSuggestedTags()`; still allow free-form so existing tags remain valid.
- Events/hooks: emit or listen for `blueprint:filter-by-tag` so other modules can apply filters without tight coupling.

## Data flow

- **Tags storage** – Unchanged: `app-tags.js` + app-data persist `tags` on projects, frameworks, guides.
- **Taxonomy** – Read-only vocabulary; no change to how tags are stored. Taxonomy only suggests/validates and powers filter UI.
- **Filtering** – taxonomy-ui reads current entities via getStoredProjects/getStoredGuides/getStoredFrameworks and filters in memory by selected tag(s).

## Phases

1. **Scaffold (this branch)** – Add app-taxonomy.js (default vocabulary + API) and app-taxonomy-ui.js (filter UI stub or minimal filter dropdown). Wire script tags in index.html.
2. **Filter projects/guides** – Connect filter control to project select and guide list; re-render or filter list by selected tags.
3. **Optional: admin vocabulary** – If needed, store facets/terms in DB (e.g. app_settings or taxonomy table) and load in app-taxonomy.js.
4. **Optional: tag picker** – Autocomplete in project/guide tag input from getSuggestedTags().