# ujin-heo/kuci-automation architecture

> Architecture diagram of the GitHub repository ujin-heo/kuci-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ujin-heo/kuci-automation
- Repository: https://github.com/ujin-heo/kuci-automation

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“전공소식 공유 메이커 v3.0”) that scrapes announcements from the 고려대학교 정보대학 website, converts them into text files, and presents them via a React frontend and a FastAPI backend.
- Frontend: React
- Backend: FastAPI with SQLAlchemy, BeautifulSoup4, and Google GenAI

##### File-Structure Analysis
- Top-level directories:
- backend/ – FastAPI service with modules, routes, and an SQLite database
- frontend/ – React application (Vite) with components, assets, and environment configs
- backend/src/modules contains specialized functionality:
- ai_summarizer.py – calls Google GenAI
- scraper.py – scrapes HTML via BeautifulSoup4
- board_infos.py & writer.py – data transformation, text file generation
- backend/src/routes maps HTTP paths to module logic (announcement, board, summarize, update_boards)
- frontend/src contains React components (BoardList, CreateResultsForm, UpdateBoardsForm) and App.jsx as entry point

##### README Insights
- Confirms tech stack and high-level flow:
User → React UI → FastAPI endpoints → modules (scraper, summarizer) → database and external AI service → results

a. Main Components
- Client (Browser) with React UI
- FastAPI Backend (four route handlers)
- SQLite Database (database.db)
- External Web Source (KU 정보대학 게시판)
- External AI Service (Google GenAI)

b. Relationships & Data Flow
1. User actions in React trigger HTTP requests to FastAPI.
3. FastAPI routes invoke:
– scraper module (HTTP GET to the university site)
– ai_summarizer module (API call to Google GenAI)
– writer & board_infos modules for text creation
4. Modules read/write to the SQLite database.
5. Processed data returned to React, then rendered in the browser.

c. Architectural Patterns & Principles
- Layered monolith for backend: separation between route layer, business-logic modules, and persistence layer
- Single-page application (SPA) on frontend
- Clear separation of concerns: scraping, summarization, data modeling

d. Key Technologies
- React + Vite (frontend)
- FastAPI (backend HTTP layer)
- SQLAlchemy (ORM)
- BeautifulSoup4 (HTML parsing)
- google-genai (AI summarization)
- SQLite (database)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Main["main.jsx"]:::frontend
        App["App.jsx"]:::frontend
        BoardList["BoardList.jsx"]:::frontend
        CreateResultsForm["CreateResultsForm.jsx"]:::frontend
        UpdateBoardsForm["UpdateBoardsForm.jsx"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "Route Handlers"
            direction TB
            Announcement["/announcement"]:::route
            Board["/board"]:::route
            Summarize["/summarize"]:::route
            UpdateBoards["/update_boards"]:::route
        end
        subgraph "Modules"
            direction TB
            Scraper["scraper"]:::module
            AISummarizer["ai_summarizer"]:::module
            BoardInfos["board_infos"]:::module
            Writer["writer"]:::module
        end
        subgraph "Persistence"
            direction TB
            DBConn["db.py"]:::db
            Models["models.py"]:::db
            SQLite["SQLite Database"]:::db
        end
    end

    %% External Services
    KU["KU 정보대학 게시판"]:::external
    GoogleAI["Google GenAI"]:::external

    %% User to Frontend
    User["User (Browser)"]:::external
    User -->|"loads app"| Main
    Main --> App
    App --> BoardList
    App --> CreateResultsForm
    App --> UpdateBoardsForm

    %% Frontend to Backend
    UpdateBoardsForm -->|POST /update_boards| UpdateBoards:::highlight
    BoardList -->|GET /board| Board
    CreateResultsForm -->|POST /announcement| Announcement
    CreateResultsForm -->|POST /summarize| Summarize

    %% Backend flows
    Announcement --> Scraper
    Board --> BoardInfos
    Summarize --> AISummarizer
    UpdateBoards --> Scraper
    UpdateBoards --> BoardInfos
    UpdateBoards --> Writer

    %% Modules to external and DB
    Scraper -->|HTTP GET| KU
    AISummarizer -->|API call| GoogleAI
    Scraper --> DBConn
    BoardInfos --> DBConn
    Writer --> DBConn
    DBConn --> Models
    Models --> SQLite
    DBConn --> SQLite

    %% Backend response to Frontend
    Announcement -->|response| App
    Board -->|response| App
    Summarize -->|response| App
    UpdateBoards -->|response| App

    %% Click Events
    click Main "https://github.com/ujin-heo/kuci-automation/blob/main/frontend/src/main.jsx"
    click App "https://github.com/ujin-heo/kuci-automation/blob/main/frontend/src/App.jsx"
    click BoardList "https://github.com/ujin-heo/kuci-automation/blob/main/frontend/src/BoardList.jsx"
    click CreateResultsForm "https://github.com/ujin-heo/kuci-automation/blob/main/frontend/src/CreateResultsFrom.jsx"
    click UpdateBoardsForm "https://github.com/ujin-heo/kuci-automation/blob/main/frontend/src/UpdateBoardsForm.jsx"
    click DBConn "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/database/db.py"
    click Models "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/database/models.py"
    click Scraper "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/modules/scraper.py"
    click AISummarizer "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/modules/ai_summarizer.py"
    click BoardInfos "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/modules/board_infos.py"
    click Writer "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/modules/writer.py"
    click Announcement "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/routes/announcement.py"
    click Board "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/routes/board.py"
    click Summarize "https://github.com/ujin-heo/kuci-automation/blob/main/backend/src/routes/summarize.py"

    %% Styles
    classDef frontend fill:#E8F4FD,stroke:#333,stroke-width:1px
    classDef backend fill:#F0F0F0,stroke:#555,stroke-width:1px
    classDef route fill:#E2E8F0,stroke:#314659,stroke-width:1px
    classDef module fill:#DFF2E1,stroke:#235E3E,stroke-width:1px
    classDef db fill:#FDEBD0,stroke:#873600,stroke-width:1px
    classDef external fill:#FAE1DD,stroke:#943126,stroke-width:1px
    classDef highlight stroke:#FF5733,stroke-width:3px,node
```
