# team-mirai-volunteer/marumie architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, monorepo Next.js application comprising two separate Next.js apps:
- **webapp/** for general public consumption (dashboards, charts, data views)
- **admin/** for internal administrators to upload CSVs, manage users, organizations, transactions, snapshots
- Both apps share domain models and utilities in **shared/**
- It uses Prisma ORM backed by a PostgreSQL database via Supabase, and follows a BFF-style layering inside each Next.js app (App Router + server components + client components)

##### High-level components
- **Browser clients**
- Public webapp (port 3000)
- Admin UI (port 3001)
- **Next.js servers**
- webapp Next.js App Router
- admin Next.js App Router
- **Shared library**
- shared/models (TypeScript domain entities)
- shared/utils (common data mapping, converters)
- **Backend services**
- Supabase PostgreSQL database
- Prisma migrations and seed (prisma/)
- Supabase local dev emulator (supabase/)
- **External systems**
- Cloud accounting services (MFクラウド, freee)—data import via CSV
- Vercel (production host + automatic DB migration on build)

##### Relationships and data flows
- User’s browser → Next.js frontend (SSR/page requests, client-side hydration)
- Next.js server components / API routes → server “usecase” layer → repository interfaces → Prisma client → PostgreSQL DB
- CSV upload in admin UI → server action → parser/validator (server/lib) → usecase → repository → DB
- Public webapp fetches data via Next.js loaders and API routes (transactions, balance‐sheet, sankey data, CSV download)
- Both apps share type definitions to guarantee consistent contracts

##### Architectural patterns and principles
- **Monorepo**: Two apps + shared code + infra in one workspace
- **Clean architecture / layered BFF**:
- app/pages/routes (controllers)
- server/usecases (business logic)
- server/repositories (abstraction interfaces)
- server/lib/prisma (data access implementation)
- **Next.js App Router**: hybrid SSR + client components
- **Domain-driven design**: explicit models (balance-snapshot, transaction, organization)
- **Infrastructure as code**: Prisma migrations, Supabase config

##### Essential elements
- Component names (e.g., webapp Next.js, admin Next.js, shared models)
- Notes about key technologies: Next.js 15, React 19, TypeScript, Prisma ORM, Supabase, Tailwind CSS, Jest tests, pnpm

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Layer"
        direction TB
        PublicBrowser["Public Browser"]:::client
        AdminBrowser["Admin Browser"]:::client
    end

    %% Next.js Apps
    subgraph "Next.js Applications"
        direction TB
        subgraph "Webapp Next.js (Port 3000)"
            direction TB
            WebAppAppRouter["Public Webapp Next.js App Router"]:::backend
            subgraph "Webapp BFF Layers"
                direction TB
                WA_API["API Routes"]:::backend
                WA_Actions["Server Actions"]:::backend
                WA_Usecases["Usecase Layer"]:::backend
                WA_Interfaces["Repository Interfaces"]:::backend
                WA_Impl["Prisma Repository Implementations"]:::backend
                WA_Lib["Lib (Prisma Client)"]:::backend
                WA_Utils["Server Utilities"]:::backend
            end
        end
        subgraph "Admin Next.js (Port 3001)"
            direction TB
            AdminAppRouter["Admin Next.js App Router"]:::backend
            subgraph "Admin BFF Layers"
                direction TB
                AA_API["API Routes"]:::backend
                AA_Actions["Server Actions"]:::backend
                AA_Usecases["Usecase Layer"]:::backend
                AA_Interfaces["Repository Interfaces"]:::backend
                AA_Impl["Prisma Repository Implementations"]:::backend
                AA_Lib["Lib (CSV Parsing & Validation)"]:::backend
            end
            AA_Client["Client Components (UI)"]:::frontend
        end
    end

    %% Shared Library
    SharedSubgraph["Shared Library"]:::shared
    subgraph "Shared Library"
        direction TB
        SharedModels["Shared Domain Models"]:::shared
        SharedUtils["Shared Utilities"]:::shared
    end

    %% Infrastructure
    subgraph "Infrastructure & External"
        direction TB
        PrismaMigrations["Prisma Migrations & Schema + Seed"]:::infra
        SupabaseEmu["Supabase Local Dev Emulator"]:::infra
        SupabaseDB["Supabase PostgreSQL Database"]:::infra
        Vercel["Vercel (Production)"]:::external
        ExternalCSV["External CSV Sources (MFクラウド, freee)"]:::external
        CICD["CI Workflow"]:::infra
        MonorepoConfig["Monorepo Workspace Config"]:::infra
    end

    %% Flows
    PublicBrowser -->|"HTTP/HTTPS"| WebAppAppRouter
    AdminBrowser -->|"HTTP/HTTPS"| AdminAppRouter

    WebAppAppRouter --> WA_API
    WebAppAppRouter --> WA_Actions
    WA_API --> WA_Usecases
    WA_Actions --> WA_Usecases
    WA_Usecases --> WA_Interfaces
    WA_Interfaces --> WA_Impl
    WA_Impl --> SupabaseDB
    WA_Lib --> SupabaseDB
    WA_Utils --> WA_Usecases

    AdminAppRouter --> AA_API
    AdminAppRouter --> AA_Actions
    AA_API --> AA_Usecases
    AA_Actions --> AA_Usecases
    AA_Usecases --> AA_Interfaces
    AA_Interfaces --> AA_Impl
    AA_Impl --> SupabaseDB
    AA_Lib --> AA_Usecases
    AA_Client --> AdminAppRouter

    %% Shared imports
    WebAppAppRouter --> SharedModels
    WebAppAppRouter --> SharedUtils
    AdminAppRouter --> SharedModels
    AdminAppRouter --> SharedUtils

    %% Infra and external
    PrismaMigrations --> SupabaseDB
    SupabaseEmu --> SupabaseDB
    Vercel --> PrismaMigrations
    Vercel --> SupabaseDB
    ExternalCSV --> AA_Actions

    CICD --> Vercel
    MonorepoConfig -.-> WebAppAppRouter
    MonorepoConfig -.-> AdminAppRouter
    MonorepoConfig -.-> SharedModels
    MonorepoConfig -.-> SharedUtils
    MonorepoConfig -.-> PrismaMigrations
    MonorepoConfig -.-> SupabaseEmu

    %% Click Events
    click WebAppAppRouter "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/app/"
    click WA_API "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/app/api/"
    click WA_Actions "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/server/actions/"
    click WA_Usecases "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/server/usecases/"
    click WA_Interfaces "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/server/repositories/interfaces/"
    click WA_Impl "https://github.com/team-mirai-volunteer/marumie/blob/develop/webapp/src/server/repositories/prisma-*.repository.ts"
    click WA_Lib "https://github.com/team-mirai-volunteer/marumie/blob/develop/webapp/src/server/lib/prisma.ts"
    click WA_Utils "https://github.com/team-mirai-volunteer/marumie/tree/develop/webapp/src/server/utils/"
    click AdminAppRouter "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/app/"
    click AA_API "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/app/api/"
    click AA_Actions "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/server/actions/"
    click AA_Usecases "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/server/usecases/"
    click AA_Interfaces "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/server/repositories/interfaces/"
    click AA_Impl "https://github.com/team-mirai-volunteer/marumie/blob/develop/admin/src/server/repositories/prisma-*.repository.ts"
    click AA_Lib "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/server/lib/"
    click AA_Client "https://github.com/team-mirai-volunteer/marumie/tree/develop/admin/src/client/components/"
    click SharedModels "https://github.com/team-mirai-volunteer/marumie/tree/develop/shared/models/"
    click SharedUtils "https://github.com/team-mirai-volunteer/marumie/tree/develop/shared/utils/"
    click PrismaMigrations "https://github.com/team-mirai-volunteer/marumie/tree/develop/prisma/"
    click SupabaseEmu "https://github.com/team-mirai-volunteer/marumie/blob/develop/supabase/config.toml"
    click CICD "https://github.com/team-mirai-volunteer/marumie/blob/develop/.github/workflows/ci.yml"
    click MonorepoConfig "https://github.com/team-mirai-volunteer/marumie/blob/develop/pnpm-workspace.yaml"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef backend fill:#fbf,stroke:#333,stroke-width:1px
    classDef shared fill:#bfb,stroke:#333,stroke-width:1px
    classDef infra fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#fbb,stroke:#333,stroke-width:1px
```
