🗺️ Bocchi The Map

Solo-friendly location discovery platform - Find the perfect spots for your alone time

Bocchi The Map is a modern, location-based review platform specifically designed for solo activities. Built with clean architecture principles and cloud-native technologies to scale effortlessly from MVP to millions of users.

🚀 Why This Matters

In our hyper-connected world, quality alone time is increasingly valuable. This platform helps people discover cafes, libraries, parks, and other venues that are genuinely comfortable for solo experiences - solving a real problem with elegant technology.

✨ Key Features

🎯 Solo-optimized discovery - Purpose-built for individual experiences
🌏 Global scalability - Multi-country support with i18n-first design
⚡ Real-time performance - Sub-200ms API responses with edge caching
🔐 Privacy-first - Secure user authentication with OAuth integration
📱 Progressive Web App - Native-like experience across all devices
🌙 Accessible design - Dark mode, screen reader support, WCAG compliance

🏗️ Architecture

Modern, scalable monorepo designed for microservice evolution:

📦 bocchi-the-map/
├── 🚀 api/          # Go + Huma (Onion Architecture)
├── 🎨 web/          # Next.js 15 + TypeScript
├── ☁️  infra/       # Terraform (Multi-cloud)
└── 📋 docs/         # Architecture decisions & guides

Tech Stack Highlights

Layer	Technology	Why
Frontend	Next.js 15 + TypeScript	App Router, Turbopack, React Server Components
Backend	Go + Huma + Protocol Buffers	Type-safe APIs, auto-generated OpenAPI docs, protobuf-driven contracts
Database	TiDB Serverless	MySQL-compatible, auto-scaling, built for cloud
Maps	MapLibre GL JS	Open-source, vector tiles, highly customizable
Storage	Cloudflare R2	PMTiles format for efficient map delivery
Hosting	Cloud Run + Vercel	Auto-scaling, edge distribution
Monitoring	New Relic + Sentry	APM, error tracking, performance insights
DevOps	Terraform + GitHub Actions	Infrastructure as Code, automated deployments

🎯 Quick Start

Prerequisites

# Required
go install golang.org/dl/go1.24@latest  # Go 1.24+
node --version                          # Node.js 20+
terraform --version                     # Terraform 1.5+

# Package managers
npm install -g pnpm                     # pnpm (preferred over npm)

# Recommended
go install github.com/cosmtrek/air@latest    # Hot reload
go install github.com/onsi/ginkgo/v2/ginkgo@latest  # BDD testing
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest # Type-safe SQL

Local Development

# Clone and setup
git clone https://github.com/necofuryai/bocchi-the-map.git
cd bocchi-the-map

# Backend (Terminal 1)
cd api
make deps && make proto     # Install deps + generate type-safe code from .proto files
make dev                    # Starts on :8080 with hot reload

# Frontend (Terminal 2)  
cd web
pnpm install                # Auto-installs Playwright for E2E tests
pnpm dev                    # Starts on :3000 with Turbopack

# Visit http://localhost:3000 🎉

Database Setup

The project uses environment-specific database initialization files:

Development/Testing: init-test.sql - Used automatically with docker-compose up
Production: init-production.sql - Used with production docker-compose configuration

# Start database for development/testing
docker-compose up -d

# Start database for production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

The database configuration supports both local development and production environments with appropriate schema initialization for each context.

Testing

# API testing (BDD with Ginkgo)
cd api
make test                   # Run all tests
ginkgo -r                   # Run BDD specs

# Web testing
cd web
pnpm test                   # Unit tests
pnpm test:e2e               # E2E tests

🏛️ Architecture Deep Dive

Backend: Clean Architecture

🧅 Onion Architecture Layers:
├── 💎 Domain     # Pure business logic, zero dependencies
├── 📋 Application # Use cases, orchestrates domain
├── 🔌 Infrastructure # Database, external APIs  
└── 🌐 Interfaces # HTTP handlers, middleware

Key Benefits:

Testable - Domain logic isolated from infrastructure
Scalable - Ready for microservice extraction
Maintainable - Clear dependency boundaries
Type-safe - ✅ Protocol Buffers fully implemented - All manual structs replaced with generated code

Frontend: Modern React

App Router - File-based routing with layouts
Server Components - Zero-JS components by default
Streaming SSR - Progressive page hydration
Edge Runtime - Deploy anywhere, run everywhere

Infrastructure: Cloud-Native

Multi-cloud ready - Abstract provider interfaces
Auto-scaling - Zero to millions with no config changes
Cost-optimized - Pay only for actual usage
Observability - Structured logging, metrics, tracing

📊 Performance Goals

Metric	Target	Current
API Response Time	< 200ms p95	🎯
Page Load Time	< 1.5s	🎯
Lighthouse Score	> 95	🎯
Bundle Size	< 200kb	🎯

🛠️ Development

API Development

cd api
make proto              # Generate type-safe Go code from .proto files
make test               # Run test suite (BDD with Ginkgo)
make build              # Build production binary
make docs               # Generate OpenAPI spec from protobuf definitions

Protocol Buffers Development Workflow:

Define API contracts - Edit .proto files in proto/ directory
Generate code - Run make proto to generate Go structs and gRPC clients
Implement services - Use generated types in infrastructure/grpc/ services
Update handlers - HTTP handlers automatically convert to/from protobuf types
Test & validate - Type safety enforced at compile time

Web Development

cd web
pnpm dev                # Dev server with Turbopack
pnpm build              # Production build
pnpm lint               # ESLint + TypeScript checking
pnpm test               # Unit/component tests with Vitest
pnpm test:ui            # Vitest with UI mode
pnpm test:coverage      # Tests with coverage report
pnpm test:e2e           # E2E tests with Playwright
pnpm test:e2e:ui        # Playwright with UI mode

Infrastructure

cd infra
terraform init          # Initialize providers
terraform plan          # Preview changes
terraform apply         # Deploy infrastructure

🚢 Deployment

Automated CI/CD

GitHub Actions - Test, build, deploy pipeline
Branch Protection - PR reviews, status checks required
Preview Deployments - Every PR gets a live environment
Blue/Green Deploys - Zero-downtime production updates

Manual Deployment

# Deploy to staging
make deploy-staging

# Deploy to production (requires approval)
make deploy-production

Cloud Run Deployment

Prerequisites

# Install and configure Google Cloud CLI
gcloud auth login

# Get your Google Cloud project ID (if you don't know it)
gcloud config get-value project
# Or list all projects: gcloud projects list

# Set your project ID (replace with your actual project ID)
gcloud config set project YOUR_PROJECT_ID

# Configure Docker for Google Container Registry
gcloud auth configure-docker

Build and Deploy API

cd api

# Build and push Docker image
./scripts/build.sh dev YOUR_PROJECT_ID asia-northeast1

# Or manual steps:
docker build -t gcr.io/YOUR_PROJECT_ID/bocchi-api:latest .
docker push gcr.io/YOUR_PROJECT_ID/bocchi-api:latest

# Deploy with Terraform
cd ../infra
terraform init
terraform apply -var="gcp_project_id=YOUR_PROJECT_ID"

Environment Setup

# Set required secrets in Google Secret Manager
# Note: You need to provide the actual secret values from your environment
# Example methods to provide secrets:
# 1. From environment variables: echo "$TIDB_PASSWORD" | gcloud secrets create tidb-password-dev --data-file=-
# 2. From file: gcloud secrets create tidb-password-dev --data-file=path/to/secret.txt
# 3. Interactive input (type secret and press Ctrl+D) - Recommended for security:
gcloud secrets create tidb-password-dev --data-file=-
gcloud secrets create new-relic-license-key-dev --data-file=-
gcloud secrets create sentry-dsn-dev --data-file=-

# Deploy Cloud Run service
gcloud run deploy bocchi-api-dev \
  --image=gcr.io/YOUR_PROJECT_ID/bocchi-api:latest \
  --platform=managed \
  --region=asia-northeast1 \
  --allow-unauthenticated

📝 Documentation

📖 API Documentation - Onion architecture guide
🎨 Frontend Guide - React patterns & components
☁️ Infrastructure Docs - Terraform modules & deployment
🏗️ Architecture Decisions - Technical choices & rationale

🎯 Roadmap

MVP - Core spot discovery and reviews ✅
Authentication System - Auth0 + JWT with enterprise security ✅
Production Infrastructure - Cloud Run + monitoring ✅
Huma v2 Integration - Type-safe APIs with auto-docs ✅
Protocol Buffers Migration - Full protobuf implementation with generated code ✅
Social Features - Follow users, curated lists
AI Recommendations - ML-powered spot suggestions
Mobile App - React Native with shared business logic
API v2 - GraphQL federation for microservices

🔐 Latest Updates (2025-06-30)

✅ Protocol Buffers Migration Completed 🎉

Full Implementation: All manual struct definitions replaced with generated Protocol Buffers code
Type Safety: 100% compile-time contract validation across all services (User, Spot, Review)
Zero Breaking Changes: Seamless migration preserving existing API behavior
Performance: Binary serialization for internal service communication
Multi-Language Ready: Shared contracts enable future TypeScript client generation

Previous Database Migration & CI/CD Improvements (2025-06-29) 🚧

Migration Fixes: Resolved idx_location index conflicts in reviews table migrations
GitHub Actions: Enhanced BDD test security with database URL consistency and debug logging
Production Ready: All migration files synchronized between development and production
CI Stability: Improved test environment setup with better error handling and security measures

Previous Security Update (2025-06-28) 🚨

Issue: Huma v2 authentication middleware had silent context propagation failure
Impact: Protected API endpoints were not properly authenticating users
Resolution: Implemented proper huma.WithValue() context handling pattern
Status: ✅ All authentication systems now fully functional and production-ready

Enhanced Security Features:

✅ Proper JWT token validation and user context propagation
✅ Protected endpoints (/api/v1/users/me, preferences, reviews) secured
✅ Auth0 Universal Login with comprehensive OAuth provider support
✅ Microservice-ready authentication architecture

📈 Analytics & Monitoring

Observability Stack

🔍 New Relic - Application performance monitoring, custom metrics, distributed tracing
🚨 Sentry - Error tracking, performance insights, real-time alerting
📊 Structured Logging - JSON logs with correlation IDs, centralized via Cloud Logging
💓 Health Checks - Kubernetes-ready probes with dependency validation

Key Metrics Tracked

Performance: API response times (p50, p95, p99), throughput, error rates
Business: Spot discoveries, review submissions, user engagement patterns
Infrastructure: Memory usage, CPU utilization, database connection pools
User Experience: Page load times, frontend errors, conversion funnels

Monitoring Endpoints

# Health check
curl https://api.bocchi-map.com/health

# Detailed system status
curl https://api.bocchi-map.com/health/detailed

# Metrics (Prometheus format)
curl https://api.bocchi-map.com/metrics

# Example metrics output:
# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",endpoint="/api/spots",status="200"} 1234
http_requests_total{method="POST",endpoint="/api/reviews",status="201"} 567

# HELP http_request_duration_seconds HTTP request duration in seconds
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{method="GET",endpoint="/api/spots",le="0.1"} 800
http_request_duration_seconds_bucket{method="GET",endpoint="/api/spots",le="0.5"} 1200
http_request_duration_seconds_sum{method="GET",endpoint="/api/spots"} 145.67
http_request_duration_seconds_count{method="GET",endpoint="/api/spots"} 1234

Alerting & Incident Response

Critical Alerts: > 5% error rate, > 2s p95 latency, dependency failures
Escalation: Slack notifications → PagerDuty → On-call engineer
Runbooks: Automated remediation for common issues

📄 License

MIT License - see LICENSE for details.

Built with ❤️ for the solo explorers

🌟 Star this repo • 🐛 Report Bug • 💡 Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 309 Commits
.claude		.claude
.github		.github
.husky		.husky
api		api
bin		bin
docs		docs
infra		infra
scripts		scripts
web		web
.commitlintrc.js		.commitlintrc.js
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
renovate.json		renovate.json

License

necofuryai/bocchi-the-map

Folders and files

Latest commit

History

Repository files navigation

🗺️ Bocchi The Map

🚀 Why This Matters

✨ Key Features

🏗️ Architecture

Tech Stack Highlights

🎯 Quick Start

Prerequisites

Local Development

Database Setup

Testing

🏛️ Architecture Deep Dive

Backend: Clean Architecture

Frontend: Modern React

Infrastructure: Cloud-Native

📊 Performance Goals

🛠️ Development

API Development

Web Development

Infrastructure

🚢 Deployment

Automated CI/CD

Manual Deployment

Cloud Run Deployment

Prerequisites

Build and Deploy API

Environment Setup

📝 Documentation

🎯 Roadmap

🔐 Latest Updates (2025-06-30)

📈 Analytics & Monitoring

Observability Stack

Key Metrics Tracked

Monitoring Endpoints

Alerting & Incident Response

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages