# digitaldemocracy2030/kouchou-ai architecture

> Architecture diagram of the GitHub repository digitaldemocracy2030/kouchou-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/digitaldemocracy2030/kouchou-ai
- Repository: https://github.com/digitaldemocracy2030/kouchou-ai

## Overview

##### Project Type and Purpose
- This is a full-stack web application designed to provide smart report generation and analysis for public input (broad listening). It is targeted to assist local government officials and political figures in their report and data analysis tasks.
- The system is built around multiple microservices including a RESTful backend API (using FastAPI), and two distinct Next.js frontends (one for report display and one for administrative tasks). There’s also a dummy server included for development and testing.

##### Analyzing the File Structure
- Top-Level Folders:
- “client” and “client-admin”: Two separate frontends for end-user report viewing and administrative management respectively.
- “server”: Contains the API, backend services, and the report generation pipeline, including additional subdirectories that support analysis (e.g., “broadlistening/pipeline” with stages, prompts, services, etc.).
- “utils/dummy-server”: Provides a mock API to support local or development setups.
- “.azure” and Azure-related files: Indicates that the project supports deployment templates and policies for hosting on Azure.
- “docker-compose” related files (such as .env.example, Dockerfiles, and compose.yaml): Confirms the use of containerization and orchestration.
- This clear separation is indicative of a microservices-like architecture with dedicated components.

##### Details from the README
- The README explicitly describes the architecture:
- API Service: Runs on port 8000. Its responsibilities include retrieving data, managing reports, and handling the processing pipeline.
- Client Frontend: Runs on port 3000. Focused on interactive visualization and user-friendly report viewing.
- Client-Admin Frontend: Runs on port 4000. Provides functionalities for report creation, editing, and system configuration.
- Additional utility (dummy-server) is provided to simulate API responses for development.
- It also highlights the importance of environment configuration (via .env files) and container orchestration via docker-compose, including static file output options.

##### Essential Elements with
- Data flow from client and client-admin to API.
- The sequential stages within the backend pipeline.
- Interactions with data storage (e.g., static metadata in server/public/meta/).

##### Final Advice
- That all critical pieces of the system (services, containers, pipelines, and deployment configurations) are represented.
- Keep clarity in the data flow and interactions for someone unfamiliar with the codebase to understand how the client, admin interface, and API work together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Compose Environment"
        subgraph "Backend Services"
            subgraph "API Service"
                API_Service["API Service (FastAPI)"]:::backend
                Routers["Routers"]:::backend
                API_Service -->|"routes"| Routers
            end
            Pipeline["Report Generation Pipeline (Extraction,Embedding,Clustering,etc.)"]:::backend
            API_Service -->|"processes"| Pipeline
            DataStorage["Data & File Storage (Metadata)"]:::storage
            API_Service -->|"reads/writes"| DataStorage
        end
        subgraph "Frontends"
            ClientFE["Client Frontend (Next.js)"]:::frontend
            ClientAdmin["Client-Admin Frontend (Next.js)"]:::frontend
            ClientFE -->|"calls"| API_Service
            ClientAdmin -->|"calls"| API_Service
        end
        DummyServer["Dummy Server"]:::aux
        ClientFE ---|"test/mock"| DummyServer
        ClientAdmin ---|"test/mock"| DummyServer
    end
    Azure["Azure Deployment Configurations"]:::cloud
    API_Service -->|"deployedTo"| Azure

    click API_Service "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/server/src"
    click Routers "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/server/src/routers"
    click ClientFE "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/client"
    click ClientAdmin "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/client-admin"
    click DummyServer "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/utils/dummy-server"
    click Pipeline "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/server/broadlistening/pipeline"
    click DataStorage "https://github.com/digitaldemocracy2030/kouchou-ai/tree/main/server/public/meta"
    click Azure "https://github.com/digitaldemocracy2030/kouchou-ai/blob/main/.azure"

    classDef backend fill:#ffccff,stroke:#cc0099,stroke-width:2px
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px
    classDef aux fill:#e0e0e0,stroke:#424242,stroke-width:2px
    classDef storage fill:#fff176,stroke:#f57f17,stroke-width:2px
    classDef cloud fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
```
