# tduckcloud/tduck-platform architecture

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

- Interactive diagram: https://gitdiagram.com/tduckcloud/tduck-platform
- Repository: https://github.com/tduckcloud/tduck-platform

## Overview

##### Project Type and Purpose
- This is a full-stack enterprise application built around a modular, no-code survey/form solution. The system is designed to allow both non-technical users (via drag‐and‐drop interfaces) and developers (through extensibility) to create, deploy, and manage dynamic form/survey data.
- The README clarifies that TDuck is a survey/form collection tool with rich components, data synchronization via WebHook, multiple external integrations (email, SMS, cloud storage) and even WeChat (WX) integration.

##### Analyzing the File Structure
- The project is structured as a Maven multi-module project. You see dedicated modules such as:
– tduck-account: Manages user accounts, authentication, tokens and authorization.
– tduck-api: Provides the main RESTful API endpoints, configuration, filters, exception handling and overall web layer.
– tduck-common: Contains shared utilities, constants, common data models and helper classes.
– tduck-form: Implements the core functionality of the form builder and survey management, with data handling, business logic, and export/import functionality.
– tduck-storage: Handles file uploads and different storage provider integrations (e.g., Aliyun, Qiniu, S3).
– tduck-webhook: Manages outbound webhooks for event notifications and integration with external systems.
– tduck-wx-mp: Handles WeChat MP (Official Account) integration, message/event handling, and related business logic.
- Additionally, you have configuration files (pom.xml, docker-compose, SQL scripts) and Docker infrastructure for containerizing the application plus SQL initialization scripts.

##### Major Components and Their Relationships
- Frontend (not in this repo but indicated in the README with Vue/ElementUI): A separate front-end project that interacts with the backend via REST API.
- API Gateway / Web Layer (tduck-api): Acts as the entry point for client requests. It integrates with the other modules using defined service interfaces.
- Account Module (tduck-account): Manages user registration, login, token authentication and other user-related operations.
- Form Module (tduck-form): Implements the form editor, survey creation and response processing. It handles complex form data (upload, dynamic logic, reporting).
- Storage Module (tduck-storage): Provides a pluggable storage system for file uploads attachments supporting multiple cloud/local providers.
- Webhook Module (tduck-webhook): Enables real-time data syncing and integration (e.g., updating external dashboards like TReport) using event-based architecture.
- WeChat Integration (tduck-wx-mp): Facilitates interaction with WeChat ecosystem (handling subscribe events, message responses, QR code generation).
- Common Module (tduck-common): Hosts shared functionality (such as constants, utility methods, exception handling) used throughout all modules.
- External Services: The system interacts with external databases (MySQL), third-party services for SMS, email and cloud storage integrations.

##### Architectural Patterns and Design Principles
- Modularity: The system is divided into clearly separated Maven modules, each handling a distinct business function.
- Layered Architecture: The API module acts as the presentation layer, while business logic is split across account, form, storage, webhook, etc.
- Integration via REST/WebHooks: Communication occurs over REST endpoints and asynchronous event-driven webhook mechanisms.
- Dependency Injection and Common Service Abstraction: Use of SpringBoot and related configurations (e.g., MybatisPlus, Jackson, SpringDoc) is evident.
- Configuration Management: External configuration files (YAML, properties) and Docker container scripts are used for environment setups.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Frontend Client (Vue/ElementUI)"]:::client

    subgraph "Backend Services"
        B["API Gateway (tduck-api)"]:::api
        C["Account Service (tduck-account)"]:::service
        D["Form Service (tduck-form)"]:::service
        E["Storage Service (tduck-storage)"]:::service
        F["Webhook Service (tduck-webhook)"]:::service
        G["WeChat Integration (tduck-wx-mp)"]:::service
        H["Common Utilities (tduck-common)"]:::common
    end

    I["MySQL Database"]:::database
    J["Docker Deployment"]:::docker
    K["External Integrations (SMS,Email,Cloud)"]:::external

    A -->|"REST_API"| B
    B -->|"auth"| C
    B -->|"form"| D
    B -->|"upload"| E
    B -->|"webhook"| F
    B -->|"wechat"| G

    C -->|"uses"| H
    D -->|"uses"| H
    E -->|"uses"| H
    F -->|"uses"| H
    G -->|"uses"| H

    D -->|"upload_to"| E
    D -->|"trigger"| F
    F -->|"notify"| K

    B -->|"db_ops"| I
    C -->|"db_ops"| I
    D -->|"db_ops"| I
    E -->|"db_ops"| I
    F -->|"db_ops"| I
    G -->|"db_ops"| I

    J -->|"deploys"| B

    click C "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-account/"
    click B "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-api/"
    click H "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-common/"
    click D "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-form/"
    click E "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-storage/"
    click F "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-webhook/"
    click G "https://github.com/tduckcloud/tduck-platform/tree/master/tduck-wx-mp/"

    classDef client fill:#aaf,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#cfc,stroke:#333,stroke-width:2px;
    classDef common fill:#ffdd88,stroke:#333,stroke-width:2px;
    classDef database fill:#fdd,stroke:#333,stroke-width:2px;
    classDef docker fill:#efe,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
```
