# casbin/casnode architecture

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

- Interactive diagram: https://gitdiagram.com/casbin/casnode
- Repository: https://github.com/casbin/casnode

## Overview

##### Project type and purpose
- This is a full‑stack, open‑source forum and social Q&A platform (“Casnode”), implemented as a Go backend + React frontend.
- Its key features include user authentication (Casdoor integration), content posting and moderation, search, notifications, file uploads, localization, and a Swagger‑powered public API.

##### File structure
Top‑level divisions:
- Backend (Go):
– main.go, controllers/, routers/, object/ (domain objects + business logic), service/ (external integrations: mail, OSS, tokenizer), conf/, util/, casdoor/, discuzx/ (adapters)
– swagger/ (API docs), Dockerfile, docker-compose.yml
- Frontend (React):
– web/src/ (components, CSS, i18n, admin & main pages, backend API wrappers), web/public/, package.json, craco.config.js
- Config & CI:
– conf/app.conf, .github/workflows/, go.mod/go.sum

##### README for additional insights
- Describes Casnode as an alternative to StackOverflow & Flarum, powered by ChatGPT and integrating with Casdoor for SSO.
- References Docker deployment, public API (Swagger), installation docs.

##### Main components and their interactions
a. Components
1. User’s browser (React SPA)
2. Go HTTP server (REST + SSR endpoints)
3. Database (e.g., MySQL/PostgreSQL)
4. Casdoor (external OAuth/AuthN service)
5. External storage (OSS)
6. Mail service (SMTP)
7. Cron jobs (object/cron.go)
8. Swagger UI (API docs)
b. Interactions
– Browser ←→ Go server: REST calls (JSON) for sign‑in, posts, search, notifications; SSR (via routers/filter_ssr.go) for initial page render.
– Go server ←→ Database: CRUD operations via object/*.go layer.
– Go server ←→ Casdoor: user authentication, user data sync (casdoor/adapter.go, discuzx/casdoor_init.go).
– Go server ←→ OSS: file uploads/downloads (service/oss.go).
– Go server ←→ Mail: email notifications (service/mail.go).
– Go server ←→ Cron: scheduled tasks like notifications cleanup or mailing list (object/cron.go).
– Swagger UI serves from swagger/ directory to document public APIs.

##### Architectural patterns and design principles
- Layered architecture (presentation → controllers → routers → service/domain → persistence)
- Adapter pattern for integrating Casdoor and DiscuzX (casdoor/, discuzx/)
- Separation of concerns: controllers handle HTTP, object layer holds business logic, service layer for external calls, util for logging/JSON/path.
- MVC‑like: routers dispatch to controllers; controllers orchestrate object methods; object methods call data stores.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User-facing components
    subgraph "Frontend Layer"
        ReactSPA["React SPA\n(i18n, Admin UI, Main UI, API clients)"]:::userFacing
        AdminUI["Admin UI"]:::userFacing
        APIClients["Frontend API Clients"]:::userFacing
        Localization["Localization (i18n)"]:::userFacing
        ReactSPA -->|uses Admin UI| AdminUI
        ReactSPA -->|uses API clients| APIClients
        ReactSPA -->|uses i18n| Localization
    end

    %% Server components
    subgraph "Backend Layer"
        GoServer["Go HTTP Server"]:::coreServer
        subgraph "Routing & Controllers"
            Routers["HTTP Routers"]:::coreServer
            Controllers["HTTP Controllers"]:::coreServer
        end
        subgraph "Domain & Service"
            ObjectLayer["Business Logic / Domain Objects"]:::coreServer
            subgraph "Service Layer"
                MailService["Mail Service"]:::coreServer
                OSSService["OSS Storage Service"]:::coreServer
                TokenizerService["Tokenizer Service"]:::coreServer
            end
            CasdoorAdapter["Casdoor Adapter"]:::coreServer
            DiscuzXAdapter["DiscuzX Adapter"]:::coreServer
            CronJobs["Scheduled Tasks\n(object/cron.go)"]:::coreServer
        end
        Conf["Configuration"]:::coreServer
        Util["Utility Functions"]:::coreServer
        Main["Server Entry Point\n(main.go)"]:::coreServer

        GoServer --> Routers
        Routers --> Controllers
        Controllers --> ObjectLayer
        ObjectLayer --> MailService
        ObjectLayer --> OSSService
        ObjectLayer --> TokenizerService
        Controllers --> CasdoorAdapter
        Controllers --> DiscuzXAdapter
        CronJobs --> ObjectLayer
        Main --> Routers
        Main --> Controllers
        Main --> Conf
        Main --> Util
    end

    %% External & Infra
    subgraph "Infrastructure"
        Database[("Database\n(MySQL/PostgreSQL)")]:::external
        CasdoorExt(("Casdoor\nAuthN Service")):::external
        OSSext(("External Storage\n(OSS)")):::external
        MailExt(("SMTP Mail Server")):::external
        SwaggerUI["Swagger UI\n(API Docs)"]:::userFacing
    end

    %% Connections
    ReactSPA -->|"REST/JSON over HTTPS"| GoServer
    ReactSPA -->|"SSR HTML"| GoServer
    GoServer -->|"SQL"| Database
    GoServer -->|"OAuth2/REST"| CasdoorExt
    GoServer -->|"HTTP API"| OSSext
    GoServer -->|"SMTP"| MailExt
    GoServer -->|"SERVE UI"| SwaggerUI
    CronJobs -->|"triggers tasks"| ObjectLayer

    %% Click Events
    click ReactSPA "https://github.com/casbin/casnode/tree/master/web/src/"
    click AdminUI "https://github.com/casbin/casnode/tree/master/web/src/admin/"
    click APIClients "https://github.com/casbin/casnode/tree/master/web/src/backend/"
    click Localization "https://github.com/casbin/casnode/blob/master/web/src/i18n.js"
    click Main "https://github.com/casbin/casnode/blob/master/main.go"
    click Routers "https://github.com/casbin/casnode/tree/master/routers/"
    click Controllers "https://github.com/casbin/casnode/tree/master/controllers/"
    click ObjectLayer "https://github.com/casbin/casnode/tree/master/object/"
    click MailService "https://github.com/casbin/casnode/blob/master/service/mail.go"
    click OSSService "https://github.com/casbin/casnode/blob/master/service/oss.go"
    click TokenizerService "https://github.com/casbin/casnode/blob/master/service/tokenizer.go"
    click CasdoorAdapter "https://github.com/casbin/casnode/tree/master/casdoor/"
    click DiscuzXAdapter "https://github.com/casbin/casnode/tree/master/discuzx/"
    click CronJobs "https://github.com/casbin/casnode/blob/master/object/cron.go"
    click SwaggerUI "https://github.com/casbin/casnode/tree/master/swagger/"
    click Conf "https://github.com/casbin/casnode/blob/master/conf/app.conf"
    click Util "https://github.com/casbin/casnode/tree/master/util/"
    click Dockerfile "https://github.com/casbin/casnode/tree/master/Dockerfile"
    click DCCompose "https://github.com/casbin/casnode/blob/master/docker-compose.yml"

    %% Styles
    classDef userFacing fill:#8ecae6,stroke:#219ebc,color:#023047
    classDef coreServer fill:#aacc00,stroke:#4b8700,color:#114d00
    classDef external fill:#dddddd,stroke:#888888,color:#333333
```
