# ricardoboss/pubnet architecture

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

- Interactive diagram: https://gitdiagram.com/ricardoboss/pubnet
- Repository: https://github.com/ricardoboss/pubnet

## Overview

##### Identify the Project Type and Purpose
PubNet is a **full-stack web application** designed as a **self-hosted alternative to pub.dev**, which serves as a package repository for Dart and Flutter packages. The primary purpose of PubNet is to provide users with the ability to fetch and upload new packages through a customized API, complemented by a user-friendly frontend interface and background worker services for package analysis and housekeeping.

##### Analyze the File Structure
- **Top-Level Directories:**
- **Backend:** Contains the API (`PubNet.API`), abstractions, DTOs, and services.
- **Frontend:** Houses the Blazor WebAssembly project (`PubNet.Client.Web`), API clients, extensions, and services.
- **Worker:** Includes the worker service (`PubNet.Worker`) responsible for executing tasks like package analysis.
- **Storage:** Comprises abstractions and implementations for blob storage, documentation storage, and package storage.
- **DB:** Manages database context, migrations, and entities using Entity Framework Core.
- **.github:** Contains GitHub workflows for CI/CD processes.
- **Configuration Files:** Includes Docker configurations, appsettings, and other project-level settings.

- **Architectural Patterns:**
- **Layered Architecture:** Separation of concerns with distinct layers for API, frontend, services, and storage.
- **CQRS (Command Query Responsibility Segregation):** Implemented within the Backend for handling commands and queries separately.
- **Microservices Elements:** Although not fully microservices, the separation between API, frontend, and worker services suggests a modular approach.

##### Examine the README for Additional Insights
- **Architecture Overview:** The solution comprises three main projects—`PubNet.API` (API), `PubNet.Frontend` (Blazor WebAssembly), and `PubNet.Worker` (background tasks).
- **Development Environment:** Utilizes Docker Compose to orchestrate services like PostgreSQL, Adminer, and Seq for logging.
- **Deployment Instructions:** Provides templates for `docker-compose.yml`, `Caddyfile`, and configuration JSON files for backend and worker services.
- **Technical Stack:** Built with .NET 8, Entity Framework Core, Blazor WebAssembly, and Docker for containerization.

##### a. Identify the Main Components
- **Frontend:**
- **PubNet.Client.Web:** Blazor WebAssembly application serving as the user interface.
- **Backend:**
- **PubNet.API:** RESTful API handling package fetch and upload operations.
- **PubNet.API.Services:** Business logic and service implementations.
- **Worker:**
- **PubNet.Worker:** Executes scheduled and unscheduled tasks for package analysis and maintenance.
- **Database:**
- **PostgreSQL:** Stores user data, package metadata, and other relational data.
- **Storage:**
- **Blob Storage:** Manages package files and related assets.
- **Docs Storage:** Handles storage of documentation files.
- **Package Storage:** Specialized storage for managing package archives.
- **Supporting Services:**
- **Caddy:** Acts as a reverse proxy.
- **Adminer:** Provides a web interface for database management.
- **Seq:** Facilitates logging and monitoring.

##### b. Determine Relationships and Interactions
- **Frontend ↔ Backend:**
- The Blazor frontend communicates with the `PubNet.API` to perform CRUD operations on packages and user accounts.
- **Backend ↔ Database:**
- `PubNet.API` interacts with PostgreSQL for persistent storage using Entity Framework Core.
- **Backend ↔ Storage:**
- APIs interact with storage services to upload and retrieve package files and documentation.
- **Worker ↔ Backend & Storage:**
- The worker service consumes APIs and storage to perform background tasks like package analysis.
- **Caddy ↔ Frontend & Backend:**
- Caddy routes incoming HTTP requests to the appropriate frontend or backend services.
- **Adminer & Seq ↔ Database & Logging:**
- Adminer manages the PostgreSQL database, while Seq aggregates logs from various services.

##### c. Highlight Architectural Patterns and Design Principles
- **Separation of Concerns:** Distinct separation between frontend, backend, worker, and storage layers.
- **Modularity:** Each component (API, frontend, worker) is modular, facilitating scalability and maintainability.
- **Containerization:** Use of Docker Compose for orchestrating services ensures consistency across development and production environments.
- **CQRS Pattern:** Enhances scalability and performance by segregating read and write operations.

##### d. Include Relevant Technologies, Frameworks, and Libraries
- **Frontend:** Blazor WebAssembly (.NET 8)
- **Backend:** ASP.NET Core (.NET 8), Entity Framework Core
- **Worker:** .NET 8 Worker Services
- **Database:** PostgreSQL
- **Storage:** Custom abstractions built for blob, docs, and package storage
- **Containerization:** Docker, Docker Compose
- **Reverse Proxy:** Caddy
- **Logging:** Seq
- **CI/CD:** GitHub Actions workflows

##### Elements

- **Clear Labels for Each Component:**
- Name each service and component accurately (e.g., PubNet.API, PubNet.Client.Web, PostgreSQL).

- **Storage:** Different shades or patterns to differentiate blob, docs, and package storage.

- Docker containers or services if depicting the deployment architecture.

##### Emphasizing Detail and Architectural Elements
- **High-Level Overview:**
- Provide an overarching view that encapsulates all major components and their interactions without delving into overly granular details.

- **Component Decomposition:**

- **Interactions and Dependencies:**
- How components depend on each other, emphasizing critical paths and data flows.

- **Scalability and Maintainability:**
- Aspects of the architecture that support scalability, such as modular services and containerization.

- **Tool Suggestions:**

- **Review and Iterate:**

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    subgraph "Frontend"
        F1["PubNet.Client.Web"]:::frontend
    end

    subgraph "Backend"
        B1["PubNet.API"]:::backend
        B2["PubNet.API.Services"]:::backend
    end

    subgraph "Worker"
        W1["PubNet.Worker"]:::worker
    end

    subgraph "Database"
        D1["PostgreSQL"]:::database
    end

    subgraph "Storage"
        S1["Blob Storage"]:::storage
        S2["Docs Storage"]:::storage
        S3["Package Storage"]:::storage
    end

    subgraph "Supporting Services"
        SVC1["Caddy"]:::supporting
        SVC2["Adminer"]:::supporting
        SVC3["Seq"]:::supporting
    end

    subgraph "CI/CD"
        CI1["GitHub Actions"]:::cicd
    end

    subgraph "Configuration Files"
        CF1["docker-compose.yml"]:::config
        CF2["appsettings.json"]:::config
    end

    %% Connections
    F1 -->|CRUD Operations| B1
    B1 -->|Uses Services| B2
    B1 -->|Reads/Writes| D1
    B1 -->|Interacts with| S1
    B1 -->|Interacts with| S2
    B1 -->|Interacts with| S3
    W1 -->|Performs Tasks| B1
    W1 -->|Accesses| S1
    W1 -->|Accesses| S2
    W1 -->|Accesses| S3
    SVC1 -->|Routes Traffic| F1
    SVC1 -->|Routes Traffic| B1
    SVC2 -->|Manages Database| D1
    SVC3 -->|Aggregates Logs| B1
    SVC3 -->|Aggregates Logs| W1
    CI1 -->|Deploys| B1
    CI1 -->|Deploys| F1
    CI1 -->|Deploys| W1
    CF1 -->|Configures| SVC1
    CF1 -->|Configures| SVC2
    CF1 -->|Configures| SVC3
    CF2 -->|Settings| B1
    CF2 -->|Settings| F1
    CF2 -->|Settings| W1

    %% Click Events
    click F1 "https://github.com/ricardoboss/pubnet/blob/develop/Frontend/PubNet.Client.Web"
    click B1 "https://github.com/ricardoboss/pubnet/blob/develop/Backend/PubNet.API"
    click B2 "https://github.com/ricardoboss/pubnet/blob/develop/Backend/PubNet.API.Services"
    click W1 "https://github.com/ricardoboss/pubnet/blob/develop/Worker/PubNet.Worker"
    click D1 "https://github.com/ricardoboss/pubnet/tree/develop/DB"
    click S1 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.BlobStorage.Abstractions"
    click S1 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.BlobStorage.Extensions"
    click S1 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.BlobStorage.LocalFileBlobStorage"
    click S2 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.DocsStorage.Abstractions"
    click S2 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.DocsStorage.LocalFileDocsStorage"
    click S3 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.PackageStorage.Abstractions"
    click S3 "https://github.com/ricardoboss/pubnet/blob/develop/Storage/PubNet.PackageStorage.BlobStorage"
    click SVC1 "https://github.com/ricardoboss/pubnet/tree/develop/Caddyfile"
    click SVC2 "https://github.com/ricardoboss/pubnet/blob/develop/docker-compose.yml"
    click SVC3 "https://github.com/ricardoboss/pubnet/blob/develop/docker-compose.yml"
    click CI1 "https://github.com/ricardoboss/pubnet/tree/develop/.github/workflows"
    click CF1 "https://github.com/ricardoboss/pubnet/blob/develop/docker-compose.yml"
    click CF1 "https://github.com/ricardoboss/pubnet/blob/develop/.dockerignore"
    click CF2 "https://github.com/ricardoboss/pubnet/blob/develop/appsettings.json"
    click CF2 "https://github.com/ricardoboss/pubnet/blob/develop/Backend/PubNet.API/appsettings.json"
    click CF2 "https://github.com/ricardoboss/pubnet/blob/develop/Frontend/PubNet.Client.Web/wwwroot/appsettings.json"
    click CF2 "https://github.com/ricardoboss/pubnet/blob/develop/Worker/PubNet.Worker/appsettings.json"

    %% Styles
    classDef frontend fill:#1f78b4,stroke:#333,stroke-width:2px;
    classDef backend fill:#33a02c,stroke:#333,stroke-width:2px;
    classDef worker fill:#6a3d9a,stroke:#333,stroke-width:2px;
    classDef database fill:#ff7f00,stroke:#333,stroke-width:2px;
    classDef storage fill:#b2df8a,stroke:#333,stroke-width:2px;
    classDef supporting fill:#a6a6a6,stroke:#333,stroke-width:2px;
    classDef cicd fill:#e31a1c,stroke:#333,stroke-width:2px;
    classDef config fill:#ffff99,stroke:#333,stroke-width:2px;

    %% Legend
    subgraph "Legend"
        L1["Frontend"]:::frontend
        L2["Backend"]:::backend
        L3["Worker"]:::worker
        L4["Database"]:::database
        L5["Storage"]:::storage
        L6["Supporting Services"]:::supporting
        L7["CI/CD"]:::cicd
        L8["Configuration Files"]:::config
    end

    style Legend fill:#f9f9f9,stroke:#333,stroke-width:1px
```
