Skip to content

Developer Manual

Complete guide for developers and DevOps engineers to set up, deploy, and maintain Jinbocho.

Sections

# Section What you'll find
1 Prerequisites System requirements: Docker, Python 3.12, Node.js 18, API keys
2 Local Development Docker Compose setup, port mapping, env files, verification
3 Backend Services auth, catalog, gateway, ai (optional) — endpoints, env vars, tests
4 Frontend React setup, TanStack Query patterns, critical gotchas
5 Database & Migrations Alembic, PostgreSQL schema, local reset
6 CI/CD GitHub Actions workflows for all services
7 Production Deployment Step-by-step Render + Neon deployment
8 Monitoring & Logging Render logs, health checks, Neon console
9 Troubleshooting Common issues and fixes
10 Architecture System diagram, bounded contexts, data flow, security

Quick Paths

I want to run Jinbocho locally

  1. Prerequisites — install Docker, Python, Node.js
  2. Local Development — create a docker-compose.yml and start all services

I want to deploy to production

  1. Prerequisites — create Neon and Render accounts
  2. Local Development — verify it works locally first
  3. Production Deployment — step-by-step Render + Neon guide

I need to understand the codebase

  1. Architecture — system diagram, bounded contexts, design decisions
  2. Backend Services — service-by-service breakdown
  3. Frontend — React architecture and critical gotchas

Something is broken

  1. Troubleshooting — grouped by area (database, CORS, JWT, cold starts)
  2. Monitoring & Logging — how to read Render logs

Technology Stack

Layer Technology
Backend Python 3.12, FastAPI, SQLAlchemy (async)
Database PostgreSQL 16 (Neon in production)
Migrations Alembic
Frontend React 18, TypeScript strict, Vite, TanStack Query, Zustand
HTTP client ky
Deployment Docker Compose (dev), Render + Neon (prod)
CI/CD GitHub Actions
Code quality mypy (strict), ruff, pytest, vitest

Before Every Commit

# Backend (run in each changed service directory)
ruff check app tests
python -m mypy app --strict
pytest tests/ -v

# Frontend
cd jinbocho-fe
npm run typecheck && npm run test