# youngyangyang04/kamanotes architecture

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

- Interactive diagram: https://gitdiagram.com/youngyangyang04/kamanotes
- Repository: https://github.com/youngyangyang04/kamanotes

## Overview

##### Project type and purpose
- Full-stack web application: “Kama Notes” is an online knowledge-sharing and note platform for programmers.
- Frontend: React + TypeScript app (user and admin interfaces).
- Backend: Spring Boot REST API + WebSocket, MyBatis persistence, Redis caching, file storage, scheduler and email tasks.

##### Top-level architecture components
a. Frontend
- User App (domain/user sections, note listings, comments, messaging)
- Admin App (category, question, user, dashboard management)
- Shared base components, domain services, state store (Redux)
b. Backend
- REST controllers (com.kama.notes.controller) exposing HTTP endpoints
- WebSocket handler (realtime messaging & notifications)
- Service layer (business logic)
- Data access layer (MyBatis mappers + XML)
- Configuration (security, web, Redis, scheduler)
- AOP aspects (NeedLogin, trace ID injection)
- Filters/interceptors (authentication, trace IDs)
- Scheduled tasks (email verification, daily stats)
- Event listeners (internal message events)
- Utilities (JWT, Markdown, file handling)
c. External systems & infrastructure
- MySQL database (note data, users, comments, stats)
- Redis cache (session tokens, rate limiting, hot data)
- Local file system (image/note attachments)
- SMTP/email server (via Spring Email tasks)
- WebSocket clients in browser
- Build/deployment: Docker (Dockerfile in front & back), Maven, Vite

##### Relationships and data flows
- Browser → HTTP(S) → Spring Boot REST API
- Browser ↔ WebSocket ↔ Spring Boot WebSocket handler
- REST API ↔ MyBatis → MySQL
- Service layer ↔ Redis for caching & sessions
- Service layer ↔ Local file system (upload/download)
- Scheduled tasks (via SchedulerConfig) publish Spring events → handlers for email and statistics
- REST API issues events to WebSocket handler for push notifications

##### Architectural patterns and principles
- Layered architecture (Controller → Service → Mapper → DB)
- MVC on backend, component/domain driven on frontend
- AOP for cross-cutting concerns (authentication, logging/tracing)
- Event-driven internals (Spring events + listeners)
- Token-based stateless auth (JWT + Spring Security)
- Caching for performance (Redis)
- Scheduled batch jobs for async tasks

##### Detail level
- Backend sub-components as collapsible:
- “Auth & AOP” (NeedLoginAspect, TokenInterceptor)
- “Scheduler & Tasks” (EmailTaskConsumer, DailyStatistics)
- “Event Bus” (MessageEvent → MessageEventListener → WebSocket push)
- Admin vs. user routes if desired
- Configuration (application-dev.yaml, Dockerfiles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        subgraph "User App"
            direction TB
            UserApp["User App\nReact, TS, Redux"]:::frontend
            URouter["User Router\nconfig.ts & index.tsx"]:::frontend
        end
        subgraph "Admin App"
            direction TB
            AdminApp["Admin App\nReact, TS, Redux"]:::frontend
            ARouter["Admin Router\nconfig.ts & index.tsx"]:::frontend
        end
        SharedComp["Shared Components\nBase"]:::frontend
        DomainSrv["Domain Services & APIs"]:::frontend
        Store["State Store\nRedux Toolkit"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        Controllers["REST Controllers\nSpring Boot"]:::backend
        WSHandler["WebSocket Handler\nSpring Boot"]:::backend
        subgraph "Auth & AOP"
            direction TB
            Aspects["AOP Aspects"]:::backend
            Filter["TraceIdFilter"]:::backend
            Interceptor["TokenInterceptor"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            SvcIface["Service Interfaces"]:::backend
            SvcImpl["Service Implementations"]:::backend
        end
        subgraph "Data Access"
            direction TB
            Mappers["MyBatis Mapper Interfaces"]:::backend
            Mappings["MyBatis XML Mappings"]:::backend
        end
        subgraph "Configuration"
            direction TB
            ConfigClasses["Configuration Classes"]:::backend
        end
        subgraph "Scheduler & Tasks"
            direction TB
            EmailTask["Email Task"]:::backend
            StatTask["Daily Statistics"]:::backend
        end
        subgraph "Event Bus"
            direction TB
            EventDef["MessageEvent"]:::backend
            EventListener["MessageEventListener"]:::backend
        end
        Utils["Utility Classes"]:::backend
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        MySQL["MySQL 8"]:::db
        Redis["Redis"]:::db
        FileSys["Local File Storage"]:::db
        EmailSrv["SMTP Server"]:::external
        DockerSetupFront["Frontend Dockerfile"]:::infra
        DockerSetupBack["Backend Dockerfile"]:::infra
    end

    %% Connections
    UserApp -->|HTTP/REST| Controllers
    AdminApp -->|HTTP/REST| Controllers
    UserApp -->|WebSocket| WSHandler

    Controllers -->|calls Service| SvcIface
    SvcIface -->|implemented by| SvcImpl
    SvcImpl -->|uses| Mappers
    SvcImpl -->|uses| Mappings
    Controllers -->|JDBC/MyBatis| MySQL
    Controllers -->|Redis| Redis
    SvcImpl -->|File I/O| FileSys
    Controllers -->|publishes| EventDef
    EmailTask -->|publishes| EventDef
    StatTask -->|publishes| EventDef
    EventDef -->|handled by| EventListener
    EventListener -->|WebSocket push| WSHandler

    Aspects -->|applies to| Controllers
    Filter -->|filters| Controllers
    Interceptor -->|intercepts| Controllers
    ConfigClasses -->|configures| Controllers
    ConfigClasses -->|configures| WSHandler
    Utils -->|used by| SvcImpl

    DockerSetupFront -->|builds| UserApp
    DockerSetupBack -->|builds| Controllers

    %% Click Events
    click UserApp "https://github.com/youngyangyang04/kamanotes/blob/main/frontend/src/apps/user/UserApp.tsx"
    click URouter "https://github.com/youngyangyang04/kamanotes/tree/main/frontend/src/apps/user/router"
    click AdminApp "https://github.com/youngyangyang04/kamanotes/blob/main/frontend/src/apps/admin/AdminApp.tsx"
    click ARouter "https://github.com/youngyangyang04/kamanotes/tree/main/frontend/src/apps/admin/router"
    click SharedComp "https://github.com/youngyangyang04/kamanotes/tree/main/frontend/src/base/components"
    click DomainSrv "https://github.com/youngyangyang04/kamanotes/tree/main/frontend/src/domain"
    click Store "https://github.com/youngyangyang04/kamanotes/blob/main/frontend/src/store/store.ts"
    click Controllers "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/controller"
    click WSHandler "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/websocket/MessageWebSocketHandler.java"
    click SvcIface "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/service"
    click SvcImpl "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/service/impl"
    click Mappers "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/mapper"
    click Mappings "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/resources/mapper"
    click ConfigClasses "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/config"
    click Aspects "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/aspect"
    click Filter "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/filter/TraceIdFilter.java"
    click Interceptor "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/interceptor/TokenInterceptor.java"
    click EmailTask "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/task/email/EmailTask.java"
    click StatTask "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/task/statistic/DailyStatistics.java"
    click EventDef "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/event/MessageEvent.java"
    click EventListener "https://github.com/youngyangyang04/kamanotes/blob/main/backend/src/main/java/com/kama/notes/listener/MessageEventListener.java"
    click Utils "https://github.com/youngyangyang04/kamanotes/tree/main/backend/src/main/java/com/kama/notes/utils"
    click DockerSetupFront "https://github.com/youngyangyang04/kamanotes/tree/main/frontend/Dockerfile"
    click DockerSetupBack "https://github.com/youngyangyang04/kamanotes/tree/main/backend/Dockerfile"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef db fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
    classDef infra fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
```
