https://github.com/sgcarstrends/sgcarstrends
API
https://github.com/sgcarstrends/sgcarstrends
api aws-lambda hono neon-postgres neondb sst typescript zod
Last synced: about 1 month ago
JSON representation
API
- Host: GitHub
- URL: https://github.com/sgcarstrends/sgcarstrends
- Owner: sgcarstrends
- Created: 2023-11-05T06:41:21.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-25T16:59:14.000Z (10 months ago)
- Last Synced: 2025-01-18T02:40:43.580Z (10 months ago)
- Topics: api, aws-lambda, hono, neon-postgres, neondb, sst, typescript, zod
- Language: TypeScript
- Homepage: https://api.sgcarstrends.com
- Size: 703 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SG Cars Trends
[](https://opensource.org/licenses/MIT)
## Overview
This monorepo provides a complete platform for SG Cars Trends, tracking Singapore's car registration statistics and Certificate of Entitlement (COE) data. The system includes:
- **Web Application**: Next.js 15 frontend with interactive charts, analytics, and AI-generated blog content
- **REST API**: Hono-based API with type-safe endpoints for car registrations and COE results
- **Integrated Data Updater**: QStash workflow-based system for fetching and processing LTA data
- **LLM Blog Generation**: Automated blog post creation using Google Gemini AI for market insights
- **Social Media Integration**: Automated posting to Discord, LinkedIn, Telegram, and Twitter with trackable redirect routes
- **Infrastructure**: SST v3 serverless deployment on AWS with multi-stage environments
- **Documentation**: Comprehensive developer documentation with Mintlify
## System Overview
```mermaid
graph TB
subgraph "Frontend"
WEB[Web App
Next.js 15]
BLOG[Blog Posts
AI Generated]
end
subgraph "Backend Services"
API[API Service
Hono Framework]
WORKFLOWS[Data Workflows
QStash]
LLM[Gemini AI
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"
AWS[AWS Lambda
SST v3]
end
WEB --> API
API --> DB
API --> REDIS
API --> WORKFLOWS
WORKFLOWS --> LTA
WORKFLOWS --> DB
WORKFLOWS --> LLM
LLM --> BLOG
WORKFLOWS --> DISCORD
WORKFLOWS --> LINKEDIN
WORKFLOWS --> TWITTER
WORKFLOWS --> TELEGRAM
API --> AWS
WEB --> AWS
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 frontend
class API,WORKFLOWS,LLM backend
class DB,REDIS data
class LTA external
class DISCORD,LINKEDIN,TWITTER,TELEGRAM social
class AWS infra
```
## Project Structure
```
sgcarstrends/
├── apps/
│ ├── api/ # Unified API service with integrated updater
│ │ ├── src/v1/ # API endpoints for data access
│ │ ├── src/lib/ # Workflows, social media, and LLM blog generation
│ │ ├── src/routes/ # Workflow endpoints and webhooks
│ │ ├── src/trpc/ # Type-safe tRPC router with authentication
│ │ └── src/config/ # Database, Redis, QStash configurations
│ ├── web/ # Next.js 15 frontend application
│ │ ├── src/app/ # Next.js App Router pages and layouts
│ │ │ ├── (social)/ # Social media redirect routes with UTM tracking
│ │ │ └── blog/ # Blog pages with AI-generated content
│ │ ├── src/components/ # React components with comprehensive tests
│ │ ├── src/actions/ # Server actions for blog and analytics
│ │ └── src/utils/ # Web-specific utility functions
│ ├── admin/ # Administrative interface for content management (unreleased)
│ └── docs/ # Mintlify documentation site
│ ├── architecture/ # System architecture documentation with Mermaid diagrams
│ └── diagrams/ # Source Mermaid diagram files (.mmd)
├── packages/
│ ├── database/ # Database schema and migrations (Drizzle ORM)
│ │ ├── src/schema/ # Schema definitions for all tables
│ │ └── migrations/ # Database migration files
│ ├── types/ # Shared TypeScript types
│ └── utils/ # Shared utility functions and Redis configuration
├── infra/ # SST v3 infrastructure configuration
│ ├── api.ts # API service configuration
│ ├── web.ts # Web application configuration
│ └── router.ts # Domain routing and DNS management
```
## Technologies
- **Frontend**: Next.js 15, React 19, TypeScript
- **UI Library**: HeroUI (NextUI successor) with professional design system
- **Styling**: Tailwind CSS v4 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**: SST v3 (Serverless Stack) on AWS
- **Scheduling**: QStash Workflows for data processing
- **LLM Integration**: Google Gemini AI for blog content generation
- **Package Management**: pnpm v10.13.1 workspace
- **Build Tools**: Turbopack for fast development builds
- **Testing**: Vitest (unit), Playwright (E2E) with comprehensive coverage
- **Linting**: Biome for consistent code style
## Documentation
📚 **Complete API documentation is available at: [docs.sgcarstrends.com](https://docs.sgcarstrends.com)**
- **[Getting Started](https://docs.sgcarstrends.com/quickstart)** - Quick start guide and authentication
- **[API Reference](https://docs.sgcarstrends.com/api-reference/overview)** - Complete endpoint documentation
- **[Developer Guides](https://docs.sgcarstrends.com/guides/data-models)** - Data models, filtering, and analytics
- **[Examples](https://docs.sgcarstrends.com/examples/javascript)** - Code examples in multiple languages
- **[Architecture](https://docs.sgcarstrends.com/architecture/system)** - System architecture diagrams and documentation
### Development Documentation
For developers working on this codebase, detailed component-specific guidance is available:
- **[Root CLAUDE.md](CLAUDE.md)** - Overall project guidance and conventions
- **[API Service](apps/api/CLAUDE.md)** - Hono framework, workflows, tRPC, and social media integration
- **[Web Application](apps/web/CLAUDE.md)** - Next.js development, HeroUI components, and blog features
- **[Database Package](packages/database/CLAUDE.md)** - Schema management, migrations, and TypeScript integration
- **[Infrastructure](infra/CLAUDE.md)** - SST deployment, AWS configuration, and domain management
## Getting Started
### Prerequisites
- Node.js >= 22
- pnpm v10.13.1
### Installation
```bash
# Clone the repository
git clone https://github.com/sgcarstrends/sgcarstrends.git
cd sgcarstrends
# Install dependencies
pnpm install
```
### Development
```bash
# Development
pnpm dev # Run all applications in development mode
pnpm dev:api # API service only
pnpm dev:web # Web application only
pnpm docs:dev # Documentation site only
# Build
pnpm build # Build all applications
pnpm build:web # Build web application only
pnpm build:admin # Build admin interface 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:api # Run API tests only
pnpm test:web # Run web tests only
pnpm test:e2e # Run E2E tests (web app)
pnpm test:e2e:ui # Run E2E tests with UI
# Code Quality
pnpm lint # Run linting on all packages
pnpm lint:api # Lint API service only
pnpm lint:web # 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
pnpm deploy:dev # Deploy all to dev environment
pnpm deploy:staging # Deploy all to staging environment
pnpm deploy:prod # Deploy all to production environment
# Service-specific deployment
pnpm deploy:api:dev # Deploy API to dev
pnpm deploy:web:dev # Deploy web to dev
```
## API Endpoints
### Public Endpoints
- `GET /` - Scalar API documentation interface
- `GET /docs` - OpenAPI specification
- `GET /health` - Health check endpoint
### Data Access (Authenticated)
- `GET /v1/cars` - Car registration data with filtering
- `GET /v1/coe` - COE bidding results
- `GET /v1/coe/pqp` - COE Prevailing Quota Premium rates
- `GET /v1/makes` - Car manufacturers
- `GET /v1/months/latest` - Latest month with data
### Workflow System (Authenticated)
- `POST /workflows/trigger` - Trigger data update workflows
- `POST /workflows/cars` - Car data processing workflow
- `POST /workflows/coe` - COE data processing workflow
- `POST /workflows/linkedin` - LinkedIn posting webhook
- `POST /workflows/twitter` - Twitter posting webhook
- `POST /workflows/discord` - Discord posting webhook
- `POST /workflows/telegram` - Telegram posting webhook
### tRPC (Authenticated)
- `POST /trpc/*` - Type-safe tRPC procedures with bearer authentication
## Repo Activity
## License
[MIT](LICENSE)