# lombord/winichat architecture

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

- Interactive diagram: https://gitdiagram.com/lombord/winichat
- Repository: https://github.com/lombord/winichat

## Overview

以下说明面向高级软件工程师，指导如何基于项目结构绘制详尽、精准的系统设计图。图中组件及注释均采用中/英双语显示。

##### 项目类型与目的 / Project Type & Purpose
- 这是一个实时 SPA 聊天应用 (Real-Time SPA Chat App)，前端使用 Vue.js + Vite，后端使用 Django + DRF + Channels，实现私聊与群聊功能，并支持多种媒体文件（图片、音频、视频）。
- Authentication via JWT，部署容器化 (Docker)，可通过 Nginx 反向代理统一路由 WebSocket 与 HTTP 请求。

##### 文件结构解读 / File Structure Analysis
- 顶层目录
- backend/ —— Django REST＋Channels 后端服务
- frontend/ —— Vite + Vue SPA 前端项目
- docker-compose.yml、docker-swarm.yml、deploy.sh —— 容器编排与部署脚本
- backend 内部
- base_app/ —— 核心 API、模型、权限、序列化、WebSocket consumer
- wini_chat/ —— Django 项目配置，ASGI/WSGI、路由、中间件、Settings
- media/ —— 本地媒体存储
- frontend 内部
- src/ —— Vue 组件、视图、路由、状态管理（Pinia/Vuex）
- public/ —— 静态资源
- proxy/ —— Nginx 或其他反向代理模板
- 配置文件：Dockerfile、.dockerignore、env 样例、tailwind、vite 配置等

##### 系统设计图要素 / Key Elements
a. 主要组件 / Main Components
- Browser SPA (客户端浏览器 / Frontend SPA)
- Nginx 反向代理 (Nginx Reverse Proxy)
- Django HTTP API (REST API Server)
- Django Channels WebSocket (WS Server)
- PostgreSQL 数据库 (PostgreSQL Database)
- 媒体文件存储 (Local Media Storage)
- JWT 认证服务 (JWT Auth Layer)
- Docker & Docker Compose (Containerization)
b. 交互与数据流 / Interactions & Data Flow
1. 浏览器通过 HTTPS 发起 REST 请求 → Nginx → Django REST → DB
2. 浏览器建立 WebSocket 连接 → Nginx → Django Channels → 在内存/Redis（可选）路由事件
3. Django 后端对 media 文件读写 → 本地文件系统 (media/)
4. JWT 令牌随 HTTP header & WebSocket 协议头传递，用于身份校验
c. 架构模式与设计原则 / Architectural Patterns
- 前后端分离 (Separation of Concerns)
- REST API + WebSocket 协同 (Hybrid Comm Pattern)
- Token-based Authentication (JWT)
- 容器化部署 (Containerized Microservices 模式)
d. 核心技术栈 / Technologies
- Frontend: Vue.js, Vite, TailwindCSS, DaisyUI
- Backend: Django, DRF, Django Channels, ASGI
- Database: PostgreSQL
- DevOps: Docker, docker-compose, Nginx

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend 前端"
        SPA["Frontend SPA (浏览器 SPA)"]:::frontend
    end

    subgraph "Reverse Proxy 反向代理"
        Nginx["Nginx Reverse Proxy (Nginx 反向代理)"]:::devops
    end

    subgraph "Backend 后端"
        subgraph "HTTP API 服务器"
            HTTPAPI["Django HTTP API (REST API 服务器)"]:::httpapi
            JWT["JWT Auth Layer (JWT 认证服务)"]:::httpapi
        end
        subgraph "WebSocket 服务"
            WS["Django Channels WebSocket 服务"]:::websocket
        end
    end

    subgraph "Storage 存储"
        DB["PostgreSQL DB (PostgreSQL 数据库)"]:::storage
        Media["Media Storage (媒体存储)"]:::storage
    end

    subgraph "DevOps 运维"
        Container["Containerization & Orchestration (Docker & Docker Compose)"]:::devops
    end

    SPA -->|"HTTPS/REST (HTTPS/REST)"| Nginx
    SPA -.->|"WebSocket Connection (WebSocket 连接)"| Nginx
    Nginx -->|"/api → Django REST (REST)"| HTTPAPI
    Nginx -->|"/ws → Django Channels (WS)"| WS
    HTTPAPI -->|"Database Read/Write (读写数据库)"| DB
    HTTPAPI -->|"Media File I/O (读写媒体文件)"| Media
    HTTPAPI -->|"JWT Refresh (JWT 刷新)"| JWT

    classDef frontend fill:#AEDBFF,stroke:#0000FF;
    classDef httpapi fill:#C6F7B2,stroke:#008000;
    classDef websocket fill:#FFC78E,stroke:#FF8C00;
    classDef storage fill:#DDDDDD,stroke:#555555;
    classDef devops fill:#E3DFFF,stroke:#800080;

    click SPA "https://github.com/lombord/winichat/tree/master/frontend/src"
    click Nginx "https://github.com/lombord/winichat/blob/master/frontend/proxy/default.conf.tpl"
    click Nginx "https://github.com/lombord/winichat/tree/master/frontend/proxy/proxy_params"
    click Nginx "https://github.com/lombord/winichat/blob/master/docker-compose.yml"
    click HTTPAPI "https://github.com/lombord/winichat/blob/master/backend/base_app/api/views.py"
    click HTTPAPI "https://github.com/lombord/winichat/blob/master/backend/base_app/api/urls.py"
    click HTTPAPI "https://github.com/lombord/winichat/blob/master/backend/base_app/api/viewsets/groups.py"
    click WS "https://github.com/lombord/winichat/blob/master/backend/base_app/api/consumers.py"
    click WS "https://github.com/lombord/winichat/blob/master/backend/base_app/api/routing.py"
    click WS "https://github.com/lombord/winichat/blob/master/backend/wini_chat/asgi.py"
    click WS "https://github.com/lombord/winichat/blob/master/backend/wini_chat/routing.py"
    click DB "https://github.com/lombord/winichat/blob/master/docker-compose.yml"
    click DB "https://github.com/lombord/winichat/blob/master/backend/wini_chat/settings.py"
    click Media "https://github.com/lombord/winichat/tree/master/backend/media/"
    click JWT "https://github.com/lombord/winichat/blob/master/backend/base_app/api/permissions.py"
    click JWT "https://github.com/lombord/winichat/blob/master/backend/base_app/api/serializers/users.py"
    click Container "https://github.com/lombord/winichat/blob/master/docker-compose.yml"
    click Container "https://github.com/lombord/winichat/blob/master/docker-swarm.yml"
    click Container "https://github.com/lombord/winichat/blob/master/deploy.sh"
    click Container "https://github.com/lombord/winichat/tree/master/backend/Dockerfile"
    click Container "https://github.com/lombord/winichat/tree/master/frontend/Dockerfile"
    click Container "https://github.com/lombord/winichat/blob/master/backend/.dockerignore"
    click Container "https://github.com/lombord/winichat/blob/master/frontend/.dockerignore"
```
