{
"markdown": "# MotorMetrics\n\n[](https://opensource.org/licenses/MIT)\n\n## Overview\n\nThis monorepo provides a complete platform for MotorMetrics, tracking Singapore's car registration statistics and Certificate of Entitlement (COE) data. The system includes:\n\n- **Web Application**: Next.js 16 frontend with Cache Components, co-located route components, enhanced homepage featuring latest COE results, interactive charts, analytics, AI-generated blog content, and integrated admin interface at `/admin` path. Also hosts the data updater workflows.\n- **Integrated Data Updater**: Vercel WDK workflow-based system for fetching and processing LTA data (consolidated into web application)\n- **LLM Blog Generation**: Automated blog post creation using Vercel AI SDK with Google Gemini for market insights (runs within web workflows)\n- **Social Media Integration**: Automated posting to Discord, LinkedIn, Telegram, and Twitter with trackable redirect routes (triggered by web workflows)\n- **MCP Server**: Published npm package for blog post CRUD operations via Claude Code\n- **Documentation Site**: Fumadocs-powered documentation for technical guides and API reference\n- **Infrastructure**: Vercel deployment with automatic CI/CD\n\n## System Overview\n\n```mermaid\ngraph TB\n subgraph \"Frontend & Workflows\"\n WEB[Web App
Next.js 16]\n BLOG[Blog Posts
AI Generated]\n WORKFLOWS[Data Workflows
Vercel WDK]\n LLM[Vercel AI SDK
Blog Generation]\n end\n\n subgraph \"Data Layer\"\n DB[(PostgreSQL
Neon)]\n REDIS[(Redis Cache
Upstash)]\n end\n\n subgraph \"External APIs\"\n LTA[LTA DataMall
Gov Data]\n end\n\n subgraph \"Social Platforms\"\n DISCORD[Discord]\n LINKEDIN[LinkedIn]\n TWITTER[Twitter]\n TELEGRAM[Telegram]\n end\n\n subgraph \"Infrastructure\"\n VERCEL[Vercel
Edge Network]\n end\n\n WEB --> WORKFLOWS\n WEB --> DB\n WEB --> REDIS\n\n WORKFLOWS --> LTA\n WORKFLOWS --> DB\n WORKFLOWS --> LLM\n LLM --> BLOG\n\n WORKFLOWS --> DISCORD\n WORKFLOWS --> LINKEDIN\n WORKFLOWS --> TWITTER\n WORKFLOWS --> TELEGRAM\n\n WEB --> VERCEL\n\n classDef frontend fill:#e1f5fe\n classDef backend fill:#f3e5f5\n classDef data fill:#e8f5e8\n classDef external fill:#fff3e0\n classDef social fill:#fce4ec\n classDef infra fill:#f1f8e9\n\n class WEB,BLOG,WORKFLOWS,LLM frontend\n class DB,REDIS data\n class LTA external\n class DISCORD,LINKEDIN,TWITTER,TELEGRAM social\n class VERCEL infra\n```\n\n## Project Structure\n\n```\nmotormetrics/\n├── apps/\n│ ├── docs/ # Fumadocs documentation site (Next.js 16)\n│ │ ├── content/ # MDX documentation files\n│ │ ├── src/app/ # Next.js App Router with docs layout\n│ │ └── src/lib/ # Fumadocs source adapter and shared config\n│ ├── mcp/ # MCP server for blog post CRUD (published to npm)\n│ │ └── src/ # TypeScript server implementation\n│ ├── web/ # Next.js 16 frontend application with integrated workflows\n│ │ ├── src/app/ # Next.js App Router pages and layouts\n│ │ │ ├── (social)/ # Social media redirect routes with UTM tracking\n│ │ │ ├── admin/ # Integrated admin interface for content management\n│ │ │ ├── blog/ # Blog pages with AI-generated content\n│ │ │ └── api/workflows/ # Vercel WDK workflow endpoints\n│ │ ├── src/lib/workflows/ # Data updater workflows and social media integration\n│ │ ├── src/queries/ # Data fetching queries (cars, COE, logos) with comprehensive tests\n│ │ ├── src/actions/ # Server actions (maintenance tasks)\n│ │ ├── src/components/ # React components with comprehensive tests\n│ │ ├── src/utils/ # Web-specific utility functions\n│ │ └── src/config/ # Database, Redis, and platform configurations\n├── packages/\n│ ├── ai/ # AI-powered blog generation package\n│ │ ├── src/generate-post.ts # 2-step blog generation\n│ │ ├── src/schemas.ts # Zod schemas for structured output\n│ │ └── src/instrumentation.ts # Langfuse telemetry\n│ ├── database/ # Database schema and migrations (Drizzle ORM)\n│ │ ├── src/schema/ # Schema definitions for all tables\n│ │ └── migrations/ # Database migration files\n│ ├── logos/ # Car logo management with Vercel Blob storage\n│ ├── types/ # Shared TypeScript types\n│ └── utils/ # Shared utility functions and Redis configuration\n```\n\n## Technologies\n\n- **Frontend**: Next.js 16.1 with Cache Components, React 19.2, TypeScript 5.8\n- **UI Library**: HeroUI v3 (`@heroui/react`) and HeroUI Pro (`@heroui-pro/react`) on Tailwind CSS v4\n- **Styling**: Tailwind CSS v4.1 with custom configuration\n- **Backend**: Node.js 22, TypeScript with strict mode\n- **API Framework**: Hono with OpenAPI documentation\n- **Database**: Neon Serverless PostgreSQL with Drizzle ORM\n- **Caching**: Upstash Redis for API responses and analytics\n- **Infrastructure**: Vercel with automatic deployments\n- **Scheduling**: Vercel WDK Workflows with Vercel Cron for data processing\n- **LLM Integration**: Vercel AI SDK with Google Gemini for blog content generation\n- **Package Management**: pnpm v11.0.0 workspace with catalog for centralised dependency management\n- **Build Tools**: Turbo v2.6.3 for monorepo orchestration, Turbopack for fast development builds\n- **Testing**: Vitest v4.0.15 (unit), Playwright (E2E) with comprehensive coverage\n- **Linting & Formatting**: Biome v2.3.0 for consistent code style, formatting, and import organisation\n\n## Documentation\n\nFor developers working on this codebase, detailed component-specific guidance is available:\n\n- **[Root CLAUDE.md](CLAUDE.md)** - Overall project guidance and conventions\n- **[Web Application](apps/web/CLAUDE.md)** - Next.js development, HeroUI components, blog features, and data updater workflows\n- **[AI Package](packages/ai/CLAUDE.md)** - AI-powered blog generation with Vercel AI SDK and Google Gemini\n- **[Database Package](packages/database/CLAUDE.md)** - Schema management, migrations, and TypeScript integration\n- **[Logos Package](packages/logos/CLAUDE.md)** - Car logo management with Vercel Blob storage\n\n### Product Documentation\n\nForward-looking product proposals and opportunity assessments are available in\nthe [`docs/product/`](docs/product/) directory:\n\n- **[Mobile App Opportunity](docs/product/2026-07-29-mobile-app-opportunity.md)** -\n Product thesis and validation path for a personalised vehicle companion\n- **[Advertiser Dashboard](docs/product/2026-04-05-advertiser-dashboard-design.md)** -\n Design proposal for a self-serve advertising platform\n\n### Architecture Documentation\n\nSystem architecture diagrams are available in the `docs/` directory:\n\n- **[docs/architecture/](docs/architecture/)** - Architecture documentation with Mermaid diagrams\n- **[docs/diagrams/](docs/diagrams/)** - Source Mermaid diagram files\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js >= 22\n- pnpm v11.0.0\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/motormetrics/motormetrics.git\ncd motormetrics\n\n# Install dependencies\npnpm install\n```\n\n#### Dependency Management\n\nThis project uses **pnpm catalog** for centralised dependency version management. Shared dependencies (React, Next.js, TypeScript, testing tools, etc.) are defined in `pnpm-workspace.yaml` and referenced by workspace packages using the `catalog:` protocol.\n\n**Key catalog packages:**\n- React ecosystem: `react` (^19.2.3), `react-dom` (^19.2.3), `next` (^16.1.0)\n- TypeScript & types: `typescript` (^5.8.3), `@types/node` (^22.16.4), `@types/react` (^19.2.0), `@types/react-dom` (^19.2.0)\n- Testing tools: `vitest` (^4.0.15), `@vitest/coverage-v8` (^4.0.15)\n- AI & LLM: `ai`, `@ai-sdk/gateway`, `@ai-sdk/openai`, `@langfuse/otel`\n- Utilities: `date-fns` (^3.6.0), `zod` (^4.1.13), `sonner` (2.0.7)\n\n**Root-level dependencies** (not in catalog):\n- Build tools: `turbo` (^2.6.3)\n- Code quality: `@biomejs/biome` (2.3.0), `husky` (^9.1.7), `lint-staged` (^16.1.5)\n- Release management: `semantic-release` (^24.0.0)\n\nThis ensures version consistency across all workspace packages and simplifies dependency upgrades.\n\n### Development\n\n```bash\n# Development\npnpm dev # Run all development servers\npnpm dev:web # Web application only\ncd apps/web && pnpm dev # Web application development\n\n# Build\npnpm build # Build all applications\npnpm build:web # Build web application only\n\n# Testing\npnpm test # Run all unit tests\npnpm test:watch # Run tests in watch mode\npnpm test:coverage # Run tests with coverage\npnpm test:web # Run web tests only\ncd apps/web && pnpm test # Web tests only\n\n# E2E Testing (Web App)\npnpm -F /web test:e2e # Run Playwright E2E tests\npnpm -F /web test:e2e:ui # Run E2E tests with Playwright UI\n\n# Code Quality\npnpm lint # Run Biome linting on all packages\npnpm format # Run Biome formatting on all packages\npnpm lint:web # Lint web application only\ncd apps/web && pnpm lint # Lint web application only\n\n# Database\npnpm db:migrate # Run database migrations\npnpm db:migrate:check # Check migration status\npnpm db:generate # Generate new migrations\npnpm db:push # Push schema changes\n```\n\n### Deployment\n\nDeployment is handled automatically by Vercel:\n- **Production**: Push to `main` branch triggers automatic deployment\n- **Preview**: Pull requests get automatic preview deployments\n\n## API Endpoints\n\n### Web Application Workflows (apps/web)\n\n**Workflow Endpoints (Vercel Cron Triggered):**\n- `GET /api/workflows/cars` - Car data processing workflow\n- `GET /api/workflows/coe` - COE data processing workflow\n- `GET /api/workflows/deregistrations` - Vehicle deregistration processing workflow\n\n## Repo Activity\n\n![Alt](https://repobeats.axiom.co/api/embed/01e0d81ecb779bfb5be18d4c7f79a33d75db9e7b.svg \"Repobeats analytics image\")\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 10172,
"sha": "f314878758fbf6ee3847e428ab6a95002be64b13be97dcd9ae9a0203b2a72d75",
"repo_slug": "sgcarstrends/sgcarstrends",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/skl_sgcarstrends_sgcarstrends_claude_skills__492767b7/readme"
}