Stack Management
Relevant source files
The following files were used as context for generating this wiki page:
Stack Management is a core system within the pcstyledev project designed to maintain a consistent and unified vocabulary for technology stacks across various projects. It ensures that diverse technical labels (e.g., "ReactJS", "React.js", "React") are mapped to a single "canonical" term, enabling accurate filtering, searching, and metadata display in the frontend portfolio.
This system is implemented through a combination of JSON-based configuration, a command-line interface (CLI) for data ingestion and maintenance, and frontend logic for UI rendering. It primarily serves to clean and validate the stack field of project entries before they are persisted to the main data store.
Sources: projects-cli/src/lib/stack.ts, pages/Projects.tsx:31-35
Core Components and Data Structures
Configuration Schema
The system's behavior is dictated by the stack-canonical.json file. This file defines the relationship between preferred labels and their variations.
| Field | Type | Description |
|---|---|---|
canonical | string[] | The master list of approved technology labels. |
aliases | Record<string, string> | A mapping of alternative names (keys) to their canonical counterparts (values). |
glossary | StackGlossaryEntry[] | Descriptive metadata for each canonical label, containing label and desc. |
Sources: projects-cli/src/lib/stack.ts:4-14, data/projects/stack-canonical.json
Normalization Logic
Normalization is the process of converting a raw list of technology strings into their canonical forms. The logic follows a specific hierarchy:
- Direct Match: If the trimmed, lowercase version of the string matches a canonical label.
- Alias Match: If the string matches a key in the
aliasesrecord, it is replaced by the associated canonical value. - Unknown Handling: If no match is found, the label is flagged as "unknown" but preserved in its original form to prevent data loss.
Sources: projects-cli/src/lib/stack.ts:51-87
Workflow and Data Flow
Stack Normalization Flow
The following diagram illustrates how raw stack data from project analysis or user input is processed.
This flow is utilized during project creation (add command), manual updates (update command), and bulk maintenance (normalize command).
Sources: projects-cli/src/lib/stack.ts:49-99, projects-cli/src/commands/add.ts:51-64, projects-cli/src/commands/normalize.ts:13-28
Extending the Canonical List
When unknown labels are encountered, the CLI provides a mechanism to extend the configuration dynamically.
CLI Commands
The system provides several operational entry points via the projects-cli:
1. normalize --fix
Scans all projects in projects.json and attempts to fix stack labels based on the current stack-canonical.json.
- Logic: Iterates through projects, applies
normalizeStackList, and reports changes or remaining unknowns. - Source: projects-cli/src/commands/normalize.ts:9-47
2. add <dir>
Uses Gemini AI to analyze a directory and generate metadata.
- Logic: The AI-detected stack is immediately passed through the normalization pipeline. If unknowns are found, the user is prompted to extend the config using
maybeExtendStackConfig. - Source: projects-cli/src/commands/add.ts:51-64
3. update <name> --field stack
Allows manual editing of a project's stack.
- Logic: Accepts a comma-separated string, splits it, and normalizes the result before saving.
- Source: projects-cli/src/commands/update.ts:153-172
Frontend Integration
On the Projects page, the stack management system powers the filtering interface. It utilizes the canonical list to generate filter buttons and calculates the frequency of each technology across the project dataset.
- Filter Matrix: Displays buttons for technologies. Technologies with higher project counts are highlighted or categorized as "top stacks".
- Search Logic: The search function checks the
stackarray of each project, which is guaranteed to contain clean, canonical labels due to the CLI-side enforcement.
Sources: pages/Projects.tsx:35-37, pages/Projects.tsx:103-128, pages/Projects.tsx:265-298
Conclusion
The Stack Management system provides the necessary infrastructure to maintain high data quality in the portfolio. By centralizing technology definitions in stack-canonical.json and enforcing them through the CLI normalization pipeline, the project ensures that the frontend "Filter Matrix" remains accurate and free from duplicate or fragmented labels.