Project Data Schema
Relevant source files
The following files were used as context for generating this wiki page:
The Project Data Schema defines the core structure for managing portfolio artifacts within the pcstyledev ecosystem. It encompasses the metadata for individual projects, the canonical technology stack definitions, and the automated analysis schemas used by the internal CLI tools to synchronize local project data with the central repository.
This schema facilitates a consistent representation of software projects across the web interface, the API layer, and the command-line management tools. It ensures that project attributes—ranging from basic identifiers to complex status metrics—are validated and formatted uniformly.
Core Project Entity
The primary data structure for the system is the Project interface. This interface defines the mandatory and optional fields required to represent a software artifact in the portfolio. Projects are stored as a collection within a centralized JSON structure.
Project Data Model
| Field | Type | Description |
|---|---|---|
id | string | A unique slug derived from the project name (lowercase, hyphens). |
name | string | The display name of the project. |
desc | string | A concise, one-sentence description. |
stack | string[] | An array of technologies/frameworks used, referencing canonical names. |
link | string (Optional) | The URL to the live hosted version of the project. |
github | string (Optional) | The URL to the project's GitHub repository. |
status | ProjectStatus | Current lifecycle state: active, maintenance, experimental, prototype, disabled. |
icon | string | A Lucide icon name representing the project. |
pinned | boolean (Optional) | Flag to prioritize the project in the UI. |
createdAt | string (ISO 8601) | Timestamp of project creation. |
updatedAt | string (ISO 8601) | Timestamp of the last update to project metadata. |
modal | object (Optional) | Extended content for detailed project viewing, containing title and content. |
Sources: lib/types.ts:3-21, projects-cli/src/lib/types.ts:3-14, data/projects/projects.json:2-354
Data Relationships
The relationship between the project data and its metadata sources is depicted below:
The diagram illustrates the hierarchy of the project data storage and how projects relate to defined statuses and the technology stack.
Sources: lib/types.ts:3-26, data/projects/stack-canonical.json:2-40
Canonical Stack Schema
To maintain data integrity across the portfolio, the system uses a canonical stack configuration. This prevents duplicate entries for the same technology (e.g., "NextJS" vs "Next.js") and provides a glossary for user-facing descriptions.
Stack Configuration Structure
The stack configuration consists of three main components:
- Canonical List: The authoritative list of supported technology names.
- Aliases: A mapping of common variations to their canonical counterpart.
- Glossary: Descriptive metadata for each technology label.
This flow represents the logic used by the CLI and API to normalize technology labels before they are committed to the project data.
Sources: data/projects/stack-canonical.json:1-186, projects-cli/src/lib/gemini.ts:168-185
Automated Analysis Schema
The system utilizes the Gemini AI model to automatically extract metadata from project directories. The PROJECT_SCHEMA defines the structured object that the AI must return to ensure compatibility with the core Project Entity.
Analysis Logic and Prompting
The CLI tool gathers project context by reading specific "priority files" (like package.json, README.md, Cargo.toml) and analyzing file extensions and directory structures.
| AI Field | Mapping to Core Project | Constraint |
|---|---|---|
id | id | Lowercase, hyphens, no special characters. |
desc | desc | One sentence, lowercase, no trailing period. |
stack | stack | 2-6 main technologies; prefer canonical names. |
status | status | Inferred based on file activity/completeness. |
Sources: projects-cli/src/lib/gemini.ts:7-38, projects-cli/src/commands/add.ts:37-47
Analysis Sequence
The sequence demonstrates the automated pipeline for discovering and documenting project metadata.
Sources: projects-cli/src/lib/gemini.ts:41-115, projects-cli/src/commands/add.ts:49-110
API Integration and Live Status
The ProjectsData schema is served via an Edge Runtime API. The API combines static project data with live metrics from external sources (WakaTime and GitHub).
Live Status Interfaces
Beyond the static project metadata, the schema supports real-time coding activity:
- WakaTimeStatus: Tracks currently active projects and languages.
- GitHubStats: Tracks public repository counts, total stars, and contribution heatmaps.
Sources: lib/types.ts:23-74, api/index.ts:153-205
Summary
The Project Data Schema serves as the backbone for the pcstyledev portfolio, bridging the gap between raw source code and a structured, searchable project database. By utilizing canonical stack definitions and AI-driven analysis, the system maintains high data quality while minimizing manual entry. The schema's extensibility allows for the integration of static project attributes with dynamic activity metrics, providing a comprehensive view of development progress.
Sources: lib/types.ts data/projects/projects.json projects-cli/src/lib/gemini.ts data/projects/stack-canonical.json api/index.ts