The Problem
Distributing pure source code and dynamic styles across multiple client environments requires more than simply hosting static files. It demands a system capable of handling metadata, versioning, and real-time context for AI assistants, while maintaining high availability and low latency.
The Solution
I built a modular API that centralizes the design system logic. It does more than serve files; it processes requests to deliver the exact version of a component, resolves its dependencies, and provides the required CSS tokens based on the user’s selected theme.
Key Modules
- Registry Module:** Manages the storage and retrieval of React component source code. It analyzes metadata so the CLI knows exactly which dependencies to install.
- Themes Module:** A dynamic styling engine that serves CSS variables based on OKLCH. It allows the CLI to inject different visual identities into a project without modifying a single line of component code.
- AI Service:** An integration layer with Groq and Vercel AI SDK that provides contextual assistance by combining design system documentation with the user’s local project configuration.
Technical Decisions
- NestJS Architecture:** Chosen for its modularity and dependency injection, making the system highly maintainable and easy to test.
- Drizzle ORM:** Implemented for its type safety and near-zero overhead, ensuring database queries are as fast as native SQL.
- Template-Based Distribution:** Instead of hardcoding utility functions like `cn`, the API serves them as templates, enabling global updates for all users without requiring CLI upgrades.
- Streaming Responses:** The AI module uses streaming to provide real-time feedback in the CLI `chat` command, significantly improving the developer experience (DX).
Challenges & Learnings
- Source Code Sanitization:** Implemented logic to clean and format code before distribution, ensuring seamless integration with the user’s linter and formatter.
- Scalable Metadata Schema:** Designed a database schema that efficiently tracks component relationships, dependency trees, and theme variables.
- Machine-to-Machine Communication:** Optimized the API specifically for CLI-to-API interactions, focusing on JSON payloads and status codes that the CLI can interpret reliably.