# yukaii/zuzugo architecture

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

- Interactive diagram: https://gitdiagram.com/yukaii/zuzugo
- Repository: https://github.com/yukaii/zuzugo

## Overview

Based on our analysis of the file tree and README, this project is a full-stack web application whose main purpose is to scrape the latest rental listings from 591 and to send notifications via chatbots (specifically for Line and Slack). The application uses Next.js for both its frontend and backend, incorporates Prisma for database interactions, and organizes its business logic and integrations within a well-structured lib folder. Additionally, there are task files (e.g., for fetching new houses), notification handlers for multiple channels, and even CI/CD configuration in GitHub Actions.

##### Main Components & Their Locations
- Frontend (UI Layer):
- The “app” and “pages” directories hold Next.js components and pages including layout, styling (globals.css, page.module.css), and routing (pages/_app.tsx).
- These parts display the user interface and serve the authentication pages (e.g., pages/auth/signin.tsx).

- Backend/API Layer:
- The “pages/api” directory defines various API endpoints including authentication (nextauth), webhook/event handlers for Slack and Line, and an endpoint for “inngest” (job orchestration).
- These endpoints expose RESTful interfaces for internal business logic and external integrations.

- Business Logic & Core Services:
- The “lib” directory contains core modules such as:
o House scraping and repository logic (e.g., lib/591House, lib/repositories/591House.ts)
o Notification services for multiple channels (console, Line, Slack – see lib/notification)
o Task scheduling and execution (lib/tasks) for periodic scraping or updates
o Integration with Inngest (lib/inngest) for event-driven tasks
o Utility functions, type definitions, and schema validations (lib/zod, lib/types.ts)

- Database:
- The “prisma” directory manages migrations, schema, and database scripts indicating use of PostgreSQL.
- Prisma is leveraged to interact with the database (see lib/prisma.ts).

- External Integration Modules:
- Slack App-related functionalities are in lib/slackApp (including command handling and installation flows).
- The README provides instructions for setting up the Slack App with proper OAuth redirects, which is reflected by API routes under pages/api/slack.

- Infrastructure & DevOps:
- CI/CD workflows are present via GitHub Actions in the .github directory.
- Configuration files (.env.example, next.config.js, tailwind.config.js, etc.) are used for environment settings and project styling.
- Testing utilities are in the tests and lib/__tests__ directories ensuring a solid test suite for components and business logic.

##### Relationships and Interactions
- The Frontend interacts with the Backend through Next.js API routes. For example, API endpoints under pages/api handle authentication, incoming webhook events, and integration setup steps.
- The API layer calls business logic functions within the lib directory. The “tasks” and “repositories” modules facilitate data scraping and processing.
- The Notification services get triggered based on events (like new rental listings) and then interact with external services such as Slack and Line.
- The database (accessed via Prisma) is the persistent store for all application data including users, notifications, rental listings, and Slack installation details.
- Inngest is used to manage asynchronous and background tasks, integrating deeply with the API logic and notifications.

##### Architectural Patterns & Design Principles
- Clear Separation of Concerns: UI, API, business logic, and infrastructure (database/external services) are modularly organized.
- MVC-like structure: Although it is a Next.js application, the separation is evident as pages (controllers/views) coordinate with lib (models/business logic).
- Event-Driven & Task Scheduling: Use of Inngest for managing tasks and notifications.
- Extensibility: The project’s design (especially the notification and repository modules) allows for easy extension, such as adding new notification channels.

##### Technologies, Frameworks, and Libraries
- Next.js: For SSR and frontend/backend integration.
- Prisma: ORM for database operations.
- Tailwind CSS, global CSS: For styling the frontend.
- Inngest: For event-driven tasks.
- Slack and Line APIs: For chatbot integration and notifications.
- Testing Libraries & Jest configurations for quality assurance.

##### Additional Detail Suggestions
- “pages/api” endpoints for Slack and Line since they reflect the integration aspect.
- Testing modules to show how the applications are verified.
- Use of modern DevOps practices (CI/CD workflows) as they are crucial to this project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend (UI Layer)
    subgraph "Frontend (UI Layer)"
        FE1("app"):::frontend
        FE2("pages"):::frontend
        FE3("app/page.tsx"):::frontend
        FE4("app/globals.css"):::frontend
        FE5("pages/_app.tsx"):::frontend
        FE6("pages/auth/signin.tsx"):::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        BE1("pages/api"):::backend
        BE2("Auth_API_[...nextauth]"):::backend
        BE3("Inngest_API"):::backend
        BE4("Line_Events_API"):::backend
        BE5("Slack_Events_API"):::backend
        BE6("Slack_Install_API"):::backend
        BE7("Slack_OAuth_Redirect_API"):::backend
    end

    %% Business Logic & Core Services
    subgraph "Business Logic & Core Services"
        BL1("lib"):::logic
        BL2("591House_Module"):::logic
        BL3("House_Repository"):::logic
        BL4("Notification_Services"):::logic
        BL5("Task_Scheduling"):::logic
        BL6("Inngest_Integration"):::logic
        BL7("Utilities_&_Types"):::logic
    end

    %% Database
    subgraph "Database"
        DB1("PostgreSQL_(Prisma)"):::database
        DB2("Prisma_Client"):::database
    end

    %% External Integrations
    subgraph "External Integrations"
        EX1("Slack_App"):::external
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        DEV1("CI/CD_(GitHub_Actions)"):::devops
        DEV2("Config_Files"):::devops
    end

    %% Connections from Frontend to Backend
    FE1 -->|"calls"| BE1
    FE2 -->|"calls"| BE1
    FE3 -->|"renders"| FE1
    FE4 -->|"styles"| FE1
    FE5 -->|"initializes"| FE2
    FE6 -->|"authenticates"| FE2

    %% Connections from Backend/API Layer to Business Logic
    BE1 -->|"delegates"| BL1
    BE2 -->|"auth_calls"| BL1
    BE3 -->|"triggers"| BL6
    BE4 -->|"handles"| BL1
    BE5 -->|"handles"| BL1
    BE6 -->|"handles"| BL1
    BE7 -->|"handles"| BL1

    %% Internal breakdown of Business Logic
    BL1 -->|"includes"| BL2
    BL2 -->|"uses"| BL3
    BL1 -->|"notifies"| BL4
    BL1 -->|"schedules"| BL5
    BL1 -->|"utilizes"| BL7

    %% Business Logic interacting with Database
    BL1 -->|"reads/writes"| DB1
    BL1 -->|"queries"| DB2

    %% Notification services call External Integrations
    BL4 -->|"sends_notification"| EX1

    %% DevOps interactions (pipeline triggers deployment)
    DEV1 -->|"deploys"| FE2
    DEV1 -->|"deploys"| BE1
    DEV1 -->|"deploys"| BL1
    DEV2 -->|"configures"| FE2
    DEV2 -->|"configures"| BE1
    DEV2 -->|"configures"| BL1

    %% Click Events
    click FE1 "https://github.com/yukaii/zuzugo/tree/main/app"
    click FE2 "https://github.com/yukaii/zuzugo/tree/main/pages"
    click FE3 "https://github.com/yukaii/zuzugo/blob/main/app/page.tsx"
    click FE4 "https://github.com/yukaii/zuzugo/blob/main/app/globals.css"
    click FE5 "https://github.com/yukaii/zuzugo/blob/main/pages/_app.tsx"
    click FE6 "https://github.com/yukaii/zuzugo/blob/main/pages/auth/signin.tsx"

    click BE1 "https://github.com/yukaii/zuzugo/tree/main/pages/api"
    click BE2 "https://github.com/yukaii/zuzugo/blob/main/pages/api/auth/[...nextauth].ts"
    click BE3 "https://github.com/yukaii/zuzugo/blob/main/pages/api/inngest.ts"
    click BE4 "https://github.com/yukaii/zuzugo/blob/main/pages/api/line/events.ts"
    click BE5 "https://github.com/yukaii/zuzugo/blob/main/pages/api/slack/events.ts"
    click BE6 "https://github.com/yukaii/zuzugo/blob/main/pages/api/slack/install.ts"
    click BE7 "https://github.com/yukaii/zuzugo/blob/main/pages/api/slack/oauth_redirect.ts"

    click BL1 "https://github.com/yukaii/zuzugo/tree/main/lib"
    click BL2 "https://github.com/yukaii/zuzugo/tree/main/lib/591House"
    click BL3 "https://github.com/yukaii/zuzugo/blob/main/lib/repositories/591House.ts"
    click BL4 "https://github.com/yukaii/zuzugo/tree/main/lib/notification"
    click BL5 "https://github.com/yukaii/zuzugo/tree/main/lib/tasks"
    click BL6 "https://github.com/yukaii/zuzugo/tree/main/lib/inngest"
    click BL7 "https://github.com/yukaii/zuzugo/blob/main/lib/types.ts"

    click DB1 "https://github.com/yukaii/zuzugo/tree/main/prisma"
    click DB2 "https://github.com/yukaii/zuzugo/blob/main/lib/prisma.ts"

    click EX1 "https://github.com/yukaii/zuzugo/tree/main/lib/slackApp"

    click DEV1 "https://github.com/yukaii/zuzugo/blob/main/.github"
    click DEV2 "https://github.com/yukaii/zuzugo/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#1D8BCE,stroke-width:2px;
    classDef backend fill:#FFD9B3,stroke:#E69500,stroke-width:2px;
    classDef logic fill:#C1E1C1,stroke:#4CAF50,stroke-width:2px;
    classDef database fill:#F7C6C7,stroke:#D32F2F,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef devops fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
```
