Skip to content

README.en.md

Latest commit

 

History

History
118 lines (80 loc) · 4.86 KB

README.en.md

File metadata and controls

118 lines (80 loc) · 4.86 KB
Raw

🏔️ Nepp-chan.ai

AI Deputy Mayor for Otoineppu Village

AGPLv3 License Website Chat

A chat application where you can talk with "Nepp-chan," the AI Deputy Mayor of Otoineppu Village, Hokkaido. By learning directly from village-specific official documents to local culture, Nepp-chan delivers natural conversations with a deep understanding of local nicknames, shops, winter snow removal, community events, and other contexts unique to Otoineppu.

In Otoineppu Village, we are experimenting with a world where AI is embraced not as a "tool" but as a "member of the community." Our concept is "Software that Exists" — not a tool, but an entity loved by the villagers.

This is an Open R&D initiative that fully discloses the development process, serving as a model case for municipalities nationwide to introduce AI-based resident support at low cost.

Website · Chat · Getting Started · Roadmap · 日本語

Overview

Generic AI lacks familiarity with the nuanced details of rural communities and often fails to provide warm, natural conversations. Unlike conventional FAQ chatbots, Nepp-chan is designed as a friendly "AI Deputy Mayor" — an approachable presence you can casually consult through natural dialogue.

To ensure no one is left behind — including those unfamiliar with digital technology — we plan to progressively expand access channels: web, mobile, LINE messaging, voice calls, and in-person kiosks. By sharing our trials and learnings from Otoineppu Village, we support other municipalities facing similar challenges.

Features

  • 🏘️ Community-Native Knowledge — Learns directly from village-specific documents, local culture, and daily contexts
  • 📱 Multi-Channel Access — Web, mobile, LINE, voice calls, and in-person kiosks (progressive rollout)
  • 🤝 Friendly Persona — Not just a tool, but a community member with personality and warmth
  • 🌐 Open R&D — Full source code disclosure for nationwide municipal adoption

Roadmap

  • Phase 1: Web/mobile chat pilot
  • Phase 2: LINE messaging
  • Phase 3: Voice call support
  • Phase 4: In-person kiosks at village hall and public facilities
  • Phase 5: Anonymized conversation analytics for policy improvement
  • Vision: "A municipality where every voice is heard"

Tech Stack

  • Framework: Hono, Mastra
  • Runtime: Cloudflare Workers / Pages
  • AI: OpenAI (GPT-5.6), Google Gemini
  • Frontend: Astro, React, TailwindCSS
  • Database: Cloudflare D1
  • Language: TypeScript

Project Structure

Directory Description
server/ Backend API (Cloudflare Workers)
web/ Chat web app (Cloudflare Pages)
lp/ Landing page (Cloudflare Pages)
widget/ Embeddable chat widget for external sites
shared/ Shared TypeScript package for web / lp / server
knowledge/ Knowledge files for RAG
identity/ Visual assets: character & logos (CC BY 4.0)

Getting Started

Prerequisites

  • Node.js >= 22.13.0
  • pnpm
  • Cloudflare account

Installation

pnpm install

Environment Variables

Local secrets live in server/.dev.vars.

cp server/.dev.vars.example server/.dev.vars

web / lp / widget select their environment via PUBLIC_ENV (VITE_ENV for widget); the URLs live in shared/src/constants/environments.ts. Unset means local, so local development needs no configuration. The deploy / deploy:prd scripts pass the environment name for dev / prd.

Initialize D1 Database

# Development (apply migrations)
pnpm db:migrate:local

Development

pnpm server:dev   # API
pnpm web:dev      # Web
pnpm lp:dev       # LP
pnpm mastra:dev   # Mastra Playground

See CLAUDE.md for local/dev URLs and detailed commands.

Production

URL
LP https://nepp-chan.ai
Web https://web.nepp-chan.ai
API https://api.nepp-chan.ai

Merging into develop triggers CI, and tagpr automatically opens a version bump PR. Merging the bump PR creates a tag + GitHub Release + production deployment.