---
name: kouchou-ai-architecture
description: "Project architecture, core services, key directories, data flow, and tech stack for the kouchou-ai repository. Use when you need an overview of components, pipeline structure, or where code lives."
---

# Kouchou-AI Architecture

## Overview
Use this skill to orient yourself in the repo and explain how the system fits together.
Remember that Kouchou-AI is a broadlistening system for the Digital Democracy 2030 project, adapted from Talk to the City for Japanese municipal use cases.

## Core services and ports
- Locate the API (FastAPI) in `apps/api/` and expect it on port 8000.
- Locate the public viewer (Next.js) in `apps/public-viewer/` and expect it on port 3000.
- Locate the admin app (Next.js) in `apps/admin/` and expect it on port 4000.
- Locate the static site builder in `apps/static-site-builder/` and expect it on port 3200.
- Expect the optional Ollama service on port 11434 for local LLM usage.
- Expect Ollama to use the ELYZA-JP model by default.

## Key directories
- Use `packages/analysis-core/src/analysis_core/` for analysis steps, orchestration, services, and workflows.
- Use `apps/api/broadlistening/pipeline/` for runtime configs, inputs, and outputs managed by the API.
- Use `apps/public-viewer/components/charts/` and `apps/public-viewer/components/report/` for report UI and charts.
- Use `apps/admin/app/create/` and `apps/admin/app/create/hooks/` for report creation UI.
- Use `apps/api/src/routers/`, `apps/api/src/services/`, `apps/api/src/schemas/`, and `apps/api/src/repositories/` for API layers.

## Pipeline architecture and report flow
- Follow the flow: CSV upload -> API validation -> pipeline run -> hierarchical output -> public viewer.
- Start API-side orchestration at `apps/api/src/services/report_launcher.py`.
- Start CLI-side orchestration at `packages/analysis-core/src/analysis_core/__main__.py` and `packages/analysis-core/src/analysis_core/orchestrator.py`.
- Expect API-managed outputs under `apps/api/broadlistening/pipeline/outputs/{report_id}/`.

## Technology stack
- Treat the backend as FastAPI + OpenAI GPT models + sentence-transformers + pandas/numpy/scipy.
- Treat the frontend as Next.js 15 + TypeScript + Chakra UI + Plotly.js.
- Use pytest, Jest, and Playwright for testing.
- Use Biome (frontend) and Ruff (backend) for linting and formatting.
- Expect Azure Blob Storage support for storage needs.
- Use Lefthook for Git hooks (pre-push) as configured in `lefthook.yml`.

## Configuration pointers
- Check `biome.json`, `apps/api/pyproject.toml`, `lefthook.yml`, and `.env.example` for core config.

## Operational notes
- Require an OpenAI API key or local LLM for full pipeline runs.
- Validate LLM output for bias before acting on results.
- Back up report data before upgrading or applying breaking changes.
- Expect breaking changes between versions.