Developer Guide

Overview

This project uses three environments below:

Development: local machine
Preview: Vercel preview env (related ADR: ADR-0001)
Production

Setup your Development environment

Prerequisites

Node.js 24 or later
Docker (for Supabase local server)

Port Allocation

This project uses ports in the 30300 series:

Port	Service
30300	Next.js dev server
30301	Grafana
30303	Jekyll (docs)
30304	OTel Collector Prometheus
30317	OTel Collector gRPC
30318	OTel Collector HTTP

Setup

Install dependencies

# create local envfile
cp .env.local.template .env.local

# install dependencies
pnpm install

# start Supabase local server
pnpm run start-db

Configure .env.local with variables shown by the command below:

# see Supabase variables
pnpm run status-db

Run database migrations

To apply migrations, run command below:

pnpm run migrate:local

pnpm run migrateis for production deployments only. It pushes migrations to the remote Supabase project. For local development, always use reset-db or migrate:local.

Create initial users

Run the user creation script to create test users:

pnpm run create-users

See this file what will be created by this command.

Start the Next.js app

pnpm dev

OpenTelemetry Setup (Optional)

To enable local tracing with OpenTelemetry:

Start the OTel infrastructure:
```
pnpm run otel:start
```

Add the following to your .env.local:

# OTel endpoint (local)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:30318

# Enable verbose spans (recommended for development)
NEXT_OTEL_VERBOSE=1

View metrics and traces in Grafana: http://localhost:30301

See ADR 0028 for details.

Documentation

This project has two types of documents:

References: helps building common understanding of the domain knowledge among stakeholders. They are generated by TypeDoc
Guides: helps understand this entire project

These two types of documents are hosted by GitHub pages

To Serve GitHub Pages on local, run command below:

cd docs && make pages

If you want to update references, you should run:

pnpm run docs:generate

Appendix

Blog posts about this app: https://rindrics.com/tags/mikazuki-munechika/ (Note: mikazuki-munechika is the development codename, named after the Japanese sword “三日月宗近”)