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