# sintaxytb/guardsman-web-origin-repo architecture

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

- Interactive diagram: https://gitdiagram.com/sintaxytb/guardsman-web-origin-repo
- Repository: https://github.com/sintaxytb/guardsman-web-origin-repo

## Overview

##### Project Type and Purpose
- Guardsman Web is a full-stack administration panel (Laravel PHP backend + Vue.js SPA frontend) designed to automate tasks (punishment expiry, data backups, statistics) and provide a management UI for users, roles, servers, logs, etc.

##### File-Structure Analysis
- Top-level “app/”, “config/”, “routes/”, “database/” directories → Laravel MVC backend.
- “resources/ts/” and “resources/styles/” → Vue 3 + TypeScript + SCSS SPA.
- “public/” → built assets and entry-point (index.php) served by Nginx/PHP-FPM.
- “app/Console” → artisan commands & scheduled tasks (purge, stats).
- Presence of “docker-compose.yml”, “.env.example” → environment configuration & containerized services (web, db).
- CI config in “.github/workflows” and Qodana static-analysis.

##### Main Components
A. Client Layer
- Browser (Admin users interacting with SPA)
B. Presentation & Proxy Layer
- NGINX reverse proxy (serves static files, routes /api → PHP-FPM, proxies /api/docs → Swagger)
C. Application Layer
- PHP-FPM running Laravel
– HTTP Kernel, Controllers (app/Http/Controllers)
– Middleware chain (authentication, CSRF, API guards)
– Service Providers (Auth, Broadcast, Events, Routes)
- Vue SPA (built by Vite)
– Components, Pages, Layouts, Pinia stores, Router
D. Scheduling & CLI Layer
- Cron daemon invoking “php artisan schedule:run” each minute
- Artisan Console Commands (auto-punishment expiry, backups, stats, purge)
E. Data Layer
- MariaDB/MySQL (migrations, seeders, Eloquent ORM)
- (Optional) Redis for queues/cache (configurable in config/queue.php, config/cache.php)
- File storage (local or S3 via config/filesystems.php)
F. External Services
- Discord API (via DiscordAPIController)
- Game API (via GameAPIController)
- OpenAPI/Swagger docs service on port 9001
- Optional Broadcast drivers (Pusher, Redis)
G. Observability & DevOps
- Sentry (error tracking)
- GitHub Actions → CI/CD (testing, code-quality)
- Docker Compose orchestration

##### Relationships & Data Flows
- Browser ↔ HTTP(S) ↔ NGINX ↔ PHP-FPM (Laravel) ↔ SQL ↔ MariaDB
- Browser requests static assets (JS/CSS) directly from NGINX’s “public/” folder
- SPA invokes REST endpoints (/api/*) to Laravel controllers
- Laravel controllers call Eloquent models → database or dispatch console jobs
- Cron → artisan scheduler → executes Console commands → interacts with Models/Services → DB or external APIs
- Laravel → External Discord/Game APIs over HTTPS
- NGINX → proxies /api/docs to Swagger UI container on port 9001

##### Architectural Patterns & Design Principles
- MVC (Laravel) + SPA (Vue) separation of concerns
- RESTful API layer for data access
- Service-Provider and IoC container for decoupling
- Middleware pipeline for cross-cutting concerns (auth, throttling)
- Command Bus pattern for console tasks
- Scheduled-Task pattern (artisan schedule)
- Event-Driven hooks (EventServiceProvider, BroadcastServiceProvider)

##### Key Technologies & Frameworks
- Backend: PHP 8.3, Laravel 10, Composer
- Frontend: Vue 3, TypeScript, Vite, Pinia, Vue Router, SCSS (CoreUI template)
- Web Server: NGINX + php-fpm.sock
- Data Store: MariaDB/MySQL, optional Redis
- External APIs: Discord, Game API
- Documentation: OpenAPI (Swagger)
- Observability: Sentry
- CI: GitHub Actions (Qodana)
- Containerization: Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["Browser (Admin UI)"]:::frontend

    %% Edge / Proxy Layer
    NGINX["NGINX Reverse Proxy"]:::infra

    %% Frontend Build
    Vite["Vite Build (Vue SPA)"]:::frontend
    Vite -->|"build"| PublicAssets

    %% Public Assets
    PublicAssets["public/ (index.php, static assets)"]:::frontend
    click PublicAssets "https://github.com/sintaxytb/guardsman-web-origin-repo/tree/main/public/"

    %% API Proxy to Swagger
    SwaggerUI["Swagger UI Service\n(port 9001)"]:::external
    NGINX -->|"proxy /api/docs"| SwaggerUI
    click SwaggerUI "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/public/openapi.json"

    %% Application Layer: PHP-FPM & Laravel
    PHP["PHP-FPM\n(Laravel)"]:::backend
    NGINX -->|"HTTP(S) /api/*"| PHP
    PHP -->|"requires bootstrap"| Bootstrap
    click Bootstrap "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/bootstrap/app.php"

    subgraph "Laravel API" 
        direction TB
        HTTPKernel["HTTP Kernel"]:::backend
        click HTTPKernel "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/app/Http/Kernel.php"
        Middleware["Middleware Chain"]:::backend
        click Middleware "https://github.com/sintaxytb/guardsman-web-origin-repo/tree/main/app/Http/Middleware/"
        Controllers["Controllers"]:::backend
        click Controllers "https://github.com/sintaxytb/guardsman-web-origin-repo/tree/main/app/Http/Controllers/"
        ServiceProviders["Service Providers"]:::backend
        click ServiceProviders "https://github.com/sintaxytb/guardsman-web-origin-repo/tree/main/app/Providers/"
        RoutesAPI["REST API Routes\n(routes/api.php)"]:::backend
        click RoutesAPI "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/routes/api.php"
        RoutesWeb["Web Routes\n(routes/web.php)"]:::backend
        click RoutesWeb "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/routes/web.php"
        Bootstrap
    end

    PHP --> HTTPKernel --> Middleware --> Controllers --> ModelsDB

    %% Scheduling & CLI Layer
    Cron["Cron Daemon"]:::infra
    Cron -->|"cron → artisan schedule:run"| ConsoleKernel

    subgraph "Artisan Console"
        direction TB
        ConsoleKernel["Console Kernel"]:::backend
        click ConsoleKernel "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/app/Console/Kernel.php"
        Commands["Artisan Commands\n(app/Console/*.php)"]:::backend
        click Commands "https://github.com/sintaxytb/guardsman-web-origin-repo/tree/main/app/Console/"
    end
    ConsoleKernel --> Commands --> ModelsDB

    %% Data Layer
    subgraph "Persistence"
        direction TB
        MariaDB["MariaDB/MySQL"]:::persistence
        Redis["Redis (cache/queue)"]:::persistence
        FileStorage["File Storage\n(local/S3)"]:::persistence
    end
    ModelsDB["Eloquent ORM & Models"]:::backend
    Migrations["Migrations\n(mysql-schema.sql)"]:::persistence
    click Migrations "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/database/schema/mysql-schema.sql"
    Seeders["Seeders"]:::persistence
    click Seeders "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/database/seeders/DatabaseSeeder.php"
    Factories["Factories"]:::persistence
    click Factories "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/database/factories/UserFactory.php"
    ConfigDB["Config: database, queue, cache, filesystems"]:::persistence
    click ConfigDB "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/config/database.php"
    click ConfigDB "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/config/queue.php"
    click ConfigDB "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/config/cache.php"
    click ConfigDB "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/config/filesystems.php"
    ModelsDB --> MariaDB
    ModelsDB --> Redis
    ModelsDB --> FileStorage
    MariaDB --> Migrations
    MariaDB --> Seeders
    MariaDB --> Factories

    %% External Services
    subgraph "External APIs"
        direction TB
        DiscordAPI["Discord API"]:::external
        GameAPI["Game API"]:::external
        Sentry["Sentry (Error Tracking)"]:::external
    end
    Controllers --> DiscordAPI
    Controllers --> GameAPI
    PHP --> Sentry
    click Sentry "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/config/sentry.php"

    %% Infrastructure & DevOps
    DockerCompose["Docker Compose"]:::infra
    click DockerCompose "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/docker-compose.yml"
    GitHubCI["GitHub Actions CI/CD"]:::infra
    click GitHubCI "https://github.com/sintaxytb/guardsman-web-origin-repo/blob/main/.github/workflows/qodana_code_quality.yml"

    %% Routes
    Browser -->|"HTTP(S)|"|NGINX
    Browser -->|"Direct fetch JS/CSS"|NGINX
    Browser -->|"Interacts via API"|PHP

    %% Build flow
    Vite --> PublicAssets --> NGINX

    %% Legend
    classDef frontend fill:#FEF3C7,stroke:#D97706
    classDef backend fill:#DBEAFE,stroke:#2563EB
    classDef persistence fill:#D1FAE5,stroke:#059669
    classDef external fill:#EDE9FE,stroke:#7C3AED
    classDef infra fill:#F3F4F6,stroke:#6B7280

    %% Orchestration arrows
    DockerCompose --> NGINX
    DockerCompose --> PHP
    DockerCompose --> MariaDB
    DockerCompose --> Redis
    DockerCompose --> SwaggerUI
```
