# lehongminh-st/st.students architecture

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

- Interactive diagram: https://gitdiagram.com/lehongminh-st/st.students
- Repository: https://github.com/lehongminh-st/st.students

## Overview

##### Main Components
- Client Layer: Web browsers or clients accessing the application via HTTPS (using the generated SSL certificates for domain st.students.dev).
- Dockerized Environment: Containers running the different parts of the system.
- Web Server Container: Uses Nginx (configured in .docker/local/nginx/default.conf) to route incoming requests.
- Application Container: The PHP/Laravel application (with the full Laravel structure under the “app”, “bootstrap”, “routes”, etc.), handling HTTP requests, business logic, and API endpoints.
- Queue Worker Container: A dedicated container running Supervisor (as shown by the .docker/local/queue/supervisord.conf) to process background jobs (like student import jobs, etc.).
- (Implicit) Database Service: Although not explicitly shown as a file in the project, the configuration (config/database.php) and migrations indicate reliance on a relational database (likely managed as a separate container/service in the Docker Compose file).

##### Establish Relationships and Interactions
- The Client Layer initiates HTTPS requests (using the st.students.dev domain) that hit the Nginx web server container.
- Nginx routes these requests into the PHP/Laravel application container which executes the requested controller, interacts with models and views, and manages the response.
- The application container communicates with the Database service for persistent storage.
- For asynchronous tasks (e.g., student import or other background processing), the application dispatches jobs to a queue which are handled by the Queue Worker container, ensuring that long running imports or notifications don’t block the user experience.

##### Architectural Patterns and Design Principles
- MVC Pattern: The distinct separation between controllers (in app/Http/Controllers), models (in app/Models), and views (in resources/views and app/View/Components).
- Event-Driven Design: The use of events (app/Events) and jobs (app/Jobs) demonstrates asynchronous processing.
- Containerized Deployment: Docker is used to encapsulate and isolate services (web server, app, queue worker) ensuring environment consistency across local and production.
- Modular Design: With distinct directories handling authentication, admin tasks, livewire components, and commands, the codebase is organized to ensure separation of concerns.

##### Relevant Technologies/Frameworks and Tools
- Laravel Framework (PHP): Core of the application logic.
- Livewire: Enhancing reactive component-based interactions in the views.
- Docker & Docker Compose: For container orchestration and environmental parity between local and production.
- Nginx: As the reverse proxy and web server managing HTTP/S requests.
- Supervisor: For managing queue worker processes.
- Make: Used for command automation in local development.
- SSL Certificates generation with mkcert, emphasizing secure development.

##### Overall, Ensure Detail and Clarity
- Do not over-simplify; separate each logically distinct service or container to capture all essential architectural elements.

## Diagram (Mermaid)

```mermaid
graph TD
    Client("Client (Browser)\nHTTPS (st.students.dev)"):::client
    WebServer("Nginx (Docker Container)\nSSL Termination via mkcert"):::web
    Client -->|"HTTPS"| WebServer

    subgraph "Laravel Application (Docker Container)"
        Entry("Entry Point (public/index.php)"):::app
        App("App Code (app directory)\nMVC: Controllers, Models, Views + Livewire"):::app
        Entry -->|"Initializes"| App
    end
    WebServer -->|"Forwards_request"| Entry

    Queue("Queue Worker (Docker Container)\nSupervisor-managed Jobs"):::queue

    subgraph "Database Service"
        DBConf("DB Config (config/database.php)"):::database
        DBMig("DB Migrations (database/migrations)"):::database
    end

    App -->|"Persist_data"| DBConf
    App -->|"Persist_data"| DBMig
    App -->|"Dispatches_jobs"| Queue

    %% Click Events
    click WebServer "https://github.com/lehongminh-st/st.students/blob/main/.docker/local/nginx/default.conf"
    click Entry "https://github.com/lehongminh-st/st.students/blob/main/public/index.php"
    click App "https://github.com/lehongminh-st/st.students/tree/main/app"
    click Queue "https://github.com/lehongminh-st/st.students/blob/main/.docker/local/queue/supervisord.conf"
    click DBConf "https://github.com/lehongminh-st/st.students/blob/main/config/database.php"
    click DBMig "https://github.com/lehongminh-st/st.students/tree/main/database/migrations"

    %% Styles
    classDef client fill:#FFDDC1,stroke:#333,stroke-width:2px;
    classDef web fill:#C1FFC1,stroke:#333,stroke-width:2px;
    classDef app fill:#FFFFC2,stroke:#333,stroke-width:2px;
    classDef queue fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef database fill:#C2E0FF,stroke:#333,stroke-width:2px;
```
