# team-mirai-volunteer/mirai-gikai architecture

> Architecture diagram of the GitHub repository team-mirai-volunteer/mirai-gikai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/team-mirai-volunteer/mirai-gikai
- Repository: https://github.com/team-mirai-volunteer/mirai-gikai

## Overview

##### Main Components
a. Frontends
- Admin UI (Next.js App Router, React Server + Client components)
- Public Web UI (Next.js App Router, React Server + Client components)
b. Backend / BaaS
- Supabase (PostgreSQL database, Auth, Storage for thumbnails)
- Next.js API Routes (web/src/app/api/chat, api/revalidate)
- Packages:
- packages/supabase (shared Supabase client lib for browser & server)
- packages/seed (DB seeding scripts)
c. AI Chat Service
- Chat handler in web/src/features/chat: uses Supabase for anonymous user, cost-tracker, Langfuse telemetry, and external LLMs.
d. CI/CD & Infrastructure
- GitHub Actions workflows (.github/workflows)
- Vercel deployments (vercel.json in both “admin” and “web”)
- Local supabase CLI (config.toml, migrations/seed.sql)

##### Relationships & Data Flows
- Admin UI ↔ Supabase Auth & API:
– Users log in via Supabase Auth, Next.js Middleware guards protected routes, UI components call Supabase client and Admin API endpoints to CRUD bills, tags, diet-sessions, stances.
- Public Web UI ↔ Supabase & API:
– SSR/SSG pages fetch bill listings, details, featured tags via Supabase queries and custom API routes (e.g., preview revalidation).
- Chat API (web) ↔ Supabase & LLM Provider:
– Incoming chat requests hit Next.js API Route → handle-chat-request → uses mirai-context & mirai-knowledge → sends prompt to LLM(s) (via prompt-provider, langfuse client) → stores usage events back to Supabase.
- Seed & Migrations ↔ Database:
– packages/seed.run.ts and supabase/migrations/*.sql initialize and evolve the schema.

##### Architectural Patterns & Principles
– Monorepo workspace (pnpm) sharing code across “admin,” “web,” and “packages.”
– Next.js App Router pattern: server components for data fetching, client components for interactivity.
– Domain-driven “features” folders encapsulating actions, API calls, components, hooks, and types.
– BaaS‐centric backend: minimal custom server code, heavy reliance on Supabase for DB, Auth, and Storage.
– Serverless API Routes for specialized features (chat, revalidation).

##### Detail Level
– Show the Next.js App Router boundary: highlight server‐side data fetching vs. client components.
– Include the middleware layer for auth checks (`middleware.ts`).
– Show the shared packages (seed & supabase client) as separate modules that both frontends import.
– Emphasize the chat service flow: request → handle-chat-request → LLM → cost-tracker → telemetry → Supabase.
– Mark how previews are revalidated via the revalidate API route.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        AdminApp["Admin Next.js App"]:::frontend
        WebApp["Web Next.js App"]:::frontend
    end

    %% API / Business Logic Layer
    subgraph "API / Business Logic Layer"
        direction TB
        SupabaseClient["Supabase Client Lib"]:::backend
        NextAPI["Next.js API Routes"]:::backend
        SeedScripts["Seed Scripts"]:::backend
    end

    %% BaaS Layer
    subgraph "BaaS Layer"
        direction TB
        SupabaseCluster["Supabase Cluster\n• Auth\n• Postgres DB\n• Storage"]:::backend
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Providers\n(OpenAI, Claude, Gemini)"]:::external
        Langfuse["Langfuse Telemetry"]:::external
    end

    %% CI/CD & Infrastructure Layer
    subgraph "CI/CD & Infrastructure"
        direction TB
        GitHubActions["GitHub Actions Workflows"]:::cicd
        VercelDeploy["Vercel Deployments"]:::cicd
        SupabaseCLI["Supabase CLI & Migrations"]:::cicd
    end

    %% Connections
    AdminApp -->|"supabase-js"| SupabaseClient
    WebApp -->|"supabase-js"| SupabaseClient

    AdminApp -->|"supabase-js"| SupabaseCluster
    WebApp -->|"supabase-js"| SupabaseCluster

    WebApp -->|"HTTP API Route"| NextAPI
    NextAPI -->|"Postgres Queries"| SupabaseCluster

    SeedScripts -->|"runs migrations"| SupabaseCluster

    %% Chat Service within WebApp
    WebApp -->|"serverless API"| NextAPI
    NextAPI -->|"invoke chat handler"| LLMProviders
    NextAPI -->|"usage events"| Langfuse
    Langfuse -->|"store telemetry"| SupabaseCluster

    %% CI/CD flows
    GitHubActions -->|"deploy via Vercel"| VercelDeploy
    GitHubActions -->|"run migrations"| SupabaseCLI
    SupabaseCLI -->|"apply migrations"| SupabaseCluster

    %% Click Events
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/admin/src/app"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/admin/src/features"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/admin/src/components"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/admin/src/lib"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/admin/src/middleware.ts"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/admin/next.config.ts"
    click AdminApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/admin/vercel.json"

    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/web/src/app"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/web/src/features"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/web/src/components"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/tree/develop/web/src/lib"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/src/middleware.ts"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/next.config.ts"
    click WebApp "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/vercel.json"

    click SupabaseClient "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/supabase/src/index.ts"
    click SupabaseClient "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/supabase/src/browser.ts"
    click SupabaseClient "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/supabase/src/admin.ts"
    click SupabaseClient "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/supabase/types/supabase.types.ts"

    click SeedScripts "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/seed/run.ts"
    click SeedScripts "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/seed/data.ts"
    click SeedScripts "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/packages/seed/bill-contents-data.ts"

    click NextAPI "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/src/app/api/chat/route.ts"
    click NextAPI "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/src/app/api/revalidate/route.ts"

    click SupabaseCLI "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/supabase/config.toml"
    click SupabaseCLI "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/supabase/migrations/*.sql"
    click SupabaseCLI "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/supabase/seed.sql"

    click GitHubActions "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/.github/workflows/code_check.yml"
    click GitHubActions "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/.github/workflows/deploy.yml"
    click GitHubActions "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/.github/workflows/pinact_check.yml"

    click VercelDeploy "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/admin/vercel.json"
    click VercelDeploy "https://github.com/team-mirai-volunteer/mirai-gikai/blob/develop/web/vercel.json"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,stroke-width:1px
    classDef backend fill:#ABEBC6,stroke:#1D8348,stroke-width:1px
    classDef external fill:#F5B041,stroke:#B9770E,stroke-width:1px
    classDef cicd fill:#D5D8DC,stroke:#7B7D7D,stroke-width:1px
```
