# zap-quebec/authpuppy architecture

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

- Interactive diagram: https://gitdiagram.com/zap-quebec/authpuppy
- Repository: https://github.com/zap-quebec/authpuppy

## Overview

##### Project Type and Purpose
- That AuthPuppy is a full-stack web application built on the symfony PHP framework. Its primary purpose is to handle user authentication, manage network connections, and act as a captive portal.
- It supports plugin extensions, which add further features or integrations to the core authentication server.

##### Main Components
a. Web Frontend:
– Located in the “apps/frontend” directory; contains configuration files (app.yml, routing.yml, etc.) and modules (home, install, node, and security-related modules such as sfGuardUser, sfGuardGroup, etc.).
– Represents the user-facing interface of the system (login forms, dashboards, and installation UI).

b. Backend / Application Logic:
– The core business logic and authentication routines reside in “lib/model/authpuppycore” and are part of the base PHP code. This includes authentication protocols, identity management, and event dispatching.
– Additionally, there is considerable orchestration of workflows in modules (like node actions handling authentication flows).

c. Plugin System:
– Located under the “plugins” directory, with at least two major plugin families: apPluginManagerPlugin (responsible for handling plugins) and third-party plugins such as sfDoctrineGuardPlugin and sfFormExtraPlugin.
– Emphasize the plugin extensibility points and how these integrate with both the frontend modules and the core authentication logic.

d. Database and ORM Layer:
– The “config/doctrine” and “lib/migration/doctrine” directories indicate usage of the Doctrine ORM for database interactions. Include migration scripts and model definitions that manage user information, nodes, connections, and plugin configurations.
– Represent the database server (MySQL/PostgreSQL) communicating with the application through Doctrine.

e. External Interfaces and Web Server:
– Since the application requires an Apache server running PHP 5, include the deployment environment and web server components.
– The “web” directory contains publicly accessible resources such as the frontend entry script (index.php) and assets (CSS, JS, images).

##### Relationships and Interactions
- Bi-directional communication between the application and the database via the doctrine ORM layer.
- Connection between external user requests (via the Apache web server) routing to the symfony application, and from there to various modules (install, node, sfGuardUser, etc.).

##### Architectural Patterns and Design Principles
- MVC Pattern: Since the application is built using symfony, modular directories in “apps/frontend/modules” represent the Controller layer (actions), Views (templates), and Models (mostly in lib/model and Doctrine files).
- Extensibility via a Plugin Architecture: The design should highlight extension points where plugins integrate into the core system, allowing developers to add new features without touching core code.
- Separation of Concerns: Different directories separate configuration (in “config” and config folders within modules), presentation (templates), and business logic.

- "Web Server / Apache + PHP5" (Deployment Environment)
- "symfony Framework" (the core framework)
- "Frontend Modules" (detailing apps/frontend with sub-modules: home, install, node, etc.)
- "Core Business Logic" (libraries under lib/model/authpuppycore and related utilities)
- "Database Layer" (via Doctrine with connected database server)
- "Plugin Manager & Plugins" (from plugins directory with major plugins like apPluginManager and sfDoctrineGuardPlugin)
- Infrastructure components (database, web server)
- Extensibility components (plugins)
- Notes on important configuration files regarding routing, security, caching, and i18n that tie into how requests are processed.

– Ensure to capture as many granular elements as possible so that every significant part of the directory structure and configuration is represented.

This detailed approach should provide a comprehensive architectural view tailored to the specifics of AuthPuppy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Web Server / Apache + PHP5"]:::infrastructure
    PR["Public Resources (web)"]:::infrastructure
    F["symfony Framework"]:::framework
    FM["Frontend Modules (apps/frontend)\n(Home,Install,Node,sfGuardUser,sfGuardGroup,sfGuardPermission)"]:::frontend
    CB["Core Business Logic (lib/model/authpuppycore)"]:::business
    PM["Plugin Manager & Plugins (plugins)"]:::plugin

    subgraph "Database Layer (Doctrine ORM)"
        DS["Schema (config/doctrine)"]:::database
        DM["Migrations (lib/migration/doctrine)"]:::database
    end

    %% Connections
    A -->|"hostsStaticFiles"| PR
    A -->|"forwardsRequests"| F
    F -->|"rendersUI"| FM
    F -->|"processesLogic"| CB
    F -->|"integrates"| PM
    FM -->|"triggersAuth"| CB
    FM -->|"readsData"| DS
    CB -->|"dbOperations"| DS
    CB -->|"updatesSchema"| DM
    PM -->|"extendsUI"| FM
    PM -->|"extendsAuth"| CB
    DS -->|"schemaUpdates"| DM

    %% Click Events
    click FM "https://github.com/zap-quebec/authpuppy/tree/master/apps/frontend"
    click CB "https://github.com/zap-quebec/authpuppy/tree/master/lib/model/authpuppycore"
    click PM "https://github.com/zap-quebec/authpuppy/tree/master/plugins"
    click DS "https://github.com/zap-quebec/authpuppy/tree/master/config/doctrine"
    click DM "https://github.com/zap-quebec/authpuppy/tree/master/lib/migration/doctrine"
    click PR "https://github.com/zap-quebec/authpuppy/tree/master/web"

    %% Styles
    classDef infrastructure fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef framework fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef business fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef plugin fill:#ffebcc,stroke:#333,stroke-width:2px;
    classDef database fill:#e6ccff,stroke:#333,stroke-width:2px;
```
