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.

Kouchou-AI Architecture

Overview

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.

kouchou-ai-architecture