# fossunited/fossunited architecture

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

- Interactive diagram: https://gitdiagram.com/fossunited/fossunited
- Repository: https://github.com/fossunited/fossunited

## Overview

##### Project type and purpose
- This is a full-stack, open-source platform built on the Frappe framework. It combines a backend Frappe app and a separate frontend dashboard (built with Vue.js and Vite) to manage FOSS United activities such as chapters, hackathons, profiles, ticketing, payments, and more.
- The README clearly describes installation instructions for the whole platform and a separate FOSS United Dashboard, which acts as a centralized administrative UI for volunteers.

##### File structure to identify main components
- Top-Level Components:
- “fossunited/”: Contains the core Frappe app including modules for doctype definitions (chapters, hackathon, profiles, payments, ticketing, etc.), API endpoints, integrations, and custom web templates.
- “dashboard/”: Contains the Vue-based frontend (UI components, pages, routing) which is used for the admin dashboard.
- “docs/”: Provides documentation on architecture, features, and usage.
- Configuration, linting, pre-commit, and build files which indicate an organized development process with CI/CD setups.
- The “fossunited” module itself is organized into different directories for various domains (chapters, hackathon, payments, ticketing, etc.), showing a modular design.
- Various integrations with external services are visible (e.g., integrations/github.py, Razorpay in payments, mailing).

##### Main architectural components
a. Frontend Components:
- FOSS United Dashboard: A Vue.js single-page application served from the “dashboard” directory. This component handles user interactions, admin controls, and leverages API requests.
- Standard Frappe Web Templates: Used for the main website pages (located within fossunited/web_template) that render public-facing content.
b. Backend Components:
- Frappe Application Server: The heart of the platform, managing business logic, handling REST API endpoints, schedulers, task processing (e.g., scheduled_tasks.py), and integrating with various doctype modules.
- Modular Doctypes: Each domain (chapters, hackathon, profiles, payments, ticketing, volunteering, etc.) is implemented as separate modules within the Frappe app.
- Integrations and Plugins: Code in “integrations”, “profile_integrations”, and “overrides” demonstrates custom integrations with external systems like GitHub or payment gateways (Razorpay).
c. Database Layer:
- MariaDB (as recommended for Frappe installation) which stores data for all doctypes, user profiles, events, etc.
d. External Services & Tools:
- Payment Gateways (Razorpay and related notification webhook logs).
- GitHub integrations and mailing systems.
- Bench and Frappe's task scheduler processes.
e. CI/CD and Development Tools:
- GitHub workflows for CI, linting, and documentation generation.
- Pre-commit hooks and configuration files ensuring code quality.

##### Relationships and interactions
- The Frappe server interacts with the MariaDB database to store and retrieve data. Illustrate this connection.
- The modular components (chapters, hackathons, profiles, payments, etc.) submitted in the Frappe app domain all communicate with the central backend framework.
- External services (e.g., payment gateway, GitHub integrations) interact with the Frappe backend; show bi-directional data flows where applicable.
- CI/CD pipelines and pre-commit hooks operate in the development process layer, supporting both frontend and backend.

##### Architectural patterns and design principles to highlight
- Modular Design: Each feature (doctype) is organized as a separate module in the “fossunited” directory.
- Separation of Concerns: Clear separation between the backend (Frappe server and myriad integrations) and the frontend (the dashboard built with Vue).
- API-driven Communication: The frontend and other external services request data or trigger actions via well-defined API endpoints on the backend.
- Structured Deployment: The use of bench, Docker-like configurations (if any), and continuous integration workflows read from the repository structure.

- Clear labels for each component (e.g., “Frappe Backend Server”, “FOSS United Dashboard (Vue.js)”, “MariaDB Database”, “Chapter Module”, “Hackathon Module”, “Payment Gateway Integration”, etc.).
- Dashboard → Frappe APIs (for user actions and admin controls).
- Frappe Backend ↔ MariaDB (for CRUD operations).
- Frappe Backend ↔ External APIs (e.g., Razorpay, GitHub).
- Critical dependency (for instance, noting that the installation works best with Frappe v15 and that the bench structure is used for deployment).

- At the top, show the client layer (users accessing the dashboard or public website).
- At the bottom, include the persistent database (MariaDB) and connections to external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Users"]
    
    subgraph "Frontend Layer"
        F1["FOSS United Dashboard (Vue.js)"]
        F2["Public Website"]
    end

    subgraph "Backend Layer"
        API["API Endpoints"]
        BE["Frappe Backend Server"]
        subgraph "Backend Modules"
            CH["Chapter Module"]
            HA["Hackathon Module"]
            PR["Profiles Module"]
            PA["Payments Module"]
            TI["Ticketing Module"]
            VO["Volunteering Module"]
        end
        EX["External Integrations"]
    end

    DB["MariaDB Database"]

    subgraph "Development & Documentation"
        CI["CI/CD & Dev Tools"]
        DOC["Documentation"]
    end

    %% Data Flow
    A -->|"accesses"| F1
    A -->|"accesses"| F2
    F1 -->|"calls"| API
    F2 -->|"calls"| API
    API -->|"forwards"| BE
    BE -->|"manages"| CH
    BE -->|"manages"| HA
    BE -->|"manages"| PR
    BE -->|"manages"| PA
    BE -->|"manages"| TI
    BE -->|"manages"| VO
    BE -->|"reads/writes"| DB
    BE -->|"integrates"| EX
    EX -->|"notifies"| BE
    CI -->|"supports"| BE
    CI -->|"supports"| F1
    DOC -->|"describes"| CI

    %% Class Definitions
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef dev fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class F1,F2,A frontend;
    class API,BE,CH,HA,PR,PA,TI,VO backend;
    class DB database;
    class EX external;
    class CI,DOC dev;

    %% Click Events
    click BE "https://github.com/fossunited/fossunited/tree/develop/fossunited/"
    click API "https://github.com/fossunited/fossunited/tree/develop/fossunited/api/"
    click CH "https://github.com/fossunited/fossunited/tree/develop/fossunited/chapters/"
    click HA "https://github.com/fossunited/fossunited/tree/develop/fossunited/foss_hackathon/"
    click PR "https://github.com/fossunited/fossunited/tree/develop/fossunited/foss_profiles/"
    click PA "https://github.com/fossunited/fossunited/tree/develop/fossunited/payments/"
    click TI "https://github.com/fossunited/fossunited/tree/develop/fossunited/ticketing/"
    click VO "https://github.com/fossunited/fossunited/tree/develop/fossunited/volunteering/"
    click F2 "https://github.com/fossunited/fossunited/tree/develop/fossunited/fossunited/web_template/"
    click F2 "https://github.com/fossunited/fossunited/tree/develop/fossunited/chapters/web_template/"
    click F1 "https://github.com/fossunited/fossunited/tree/develop/dashboard/"
    click EX "https://github.com/fossunited/fossunited/tree/develop/fossunited/integrations/"
    click EX "https://github.com/fossunited/fossunited/tree/develop/fossunited/profile_integrations/"
    click EX "https://github.com/fossunited/fossunited/tree/develop/fossunited/overrides/"
    click CI "https://github.com/fossunited/fossunited/tree/develop/.github/workflows/"
    click DOC "https://github.com/fossunited/fossunited/tree/develop/docs/"
```
