# anasanzari/bullz-and-bears architecture

> Architecture diagram of the GitHub repository anasanzari/bullz-and-bears, 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/anasanzari/bullz-and-bears
- Repository: https://github.com/anasanzari/bullz-and-bears

## Overview

##### Main Components

- Backend Server (Laravel):
- Controllers and API endpoints are located in app/Http/Controllers (including AdminController, ApiController, FinanceApiController, etc.).
- Console Commands (found in app/Console/Commands) handle scheduled tasks/cron jobs (like DayEndUpdate, DayStartUpdate, StockUpdate, etc.) to update stock prices and game data.
- Models (spread across app/*.php, e.g., Stock.php, BoughtStock.php, Transaction.php, etc.) represent business logic and data entities.
- Configuration for game settings is available in config/bullz.php.

- Frontend Application:
- HTML, JavaScript, and templates exist under resources/src (with separation between “admin” and “app” for different interfaces).
- CSS/SCSS assets for styling are found in resources/assets/sass and are compiled via Grunt tasks (see Gruntfile.js) and Node packages (npm install, bower install).
- The public folder serves as the entry point (public/index.php) for user requests.

- Database:
- The application uses a database with several core tables: stocks, bought stocks, short sell, schedules, and history (as highlighted in the README).
- Migrations and seeders in the database/ folder set up and initialize the data model.

- External Services and Tools:
- Grunt is used for serving and building the frontend.
- PHP Artisan commands manage migrations, seeds, and cron jobs.
- Third-party integrations such as Facebook App configuration (with production and test app IDs) are mentioned for social features.
- CSS frameworks like Materialize (with various SCSS files in both app and sass-cache folders) support the styling.

##### Relationships and Interactions

- The Frontend and Backend:
- The frontend (running on http://localhost:8080) communicates with the Laravel backend via API endpoints provided by controllers in app/Http.

- Database Interactions:
- Migration and seeding process that initializes database tables and sample data.

- Cron/Console Commands:
- A scheduled or background process component (in app/Console/Commands) that periodically updates the stocks table in the database.
- That these commands use PHP Artisan (e.g., php artisan update:initStocks, php artisan list for 'update' commands) and depend on PHP’s Curl extension for external requests.

- Asset Pipeline:
- Dependency chain where Node (npm, bower) and Grunt manage the asset compilation from SCSS to CSS and bundling JavaScript.

##### Architectural Patterns and Design Principles

- Use the MVC pattern for the Laravel backend (Models, Views, Controllers).
- Separation of concerns: distinct layers for handling business logic (Models/Console), API services (Controllers), and presentation (Frontend templates and JS controllers).
- Use of scheduled batch processing for live updating stocks (using cron jobs) which is a core design element.
- Use of modular design on the frontend where controllers, directives, filters, and services are separated into their own files, facilitating maintainability and scalability.

##### Relevant Technologies, Frameworks, and Libraries

- PHP (Laravel framework) for backend.
- JavaScript (likely AngularJS or similar framework, as seen in the structure of controllers/directives) for the frontend.
- Node.js ecosystem (npm, Grunt, Bower) for dependency management and asset compilation.
- Sass for CSS preprocessing with Materialize as a UI framework.
- Database (MySQL or a similar RDBMS) recommended by Laravel and migration files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Client Browser"]:::frontend
        B["Frontend Application"]:::frontend
        C["Public Entry Point"]:::frontend
        D["SCSS Assets"]:::asset
        E["Grunt Build Tool"]:::asset
        F["Compiled Assets"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        G["API Controllers"]:::backend
        H["Console Commands (Cron Jobs)"]:::backend
        subgraph "Business Models"
            I["Stock"]:::model
            J["BoughtStock"]:::model
            K["Transaction"]:::model
            L["User"]:::model
        end
        M["Configuration"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        N["Database<br/>(Stocks, BoughtStocks, ShortSell, Schedules, History, Users)"]:::database
        O["DB Migrations"]:::database
        P["DB Seeders"]:::database
    end

    %% External & Build Tools
    subgraph "External / Build Tools"
        Q["Asset Build Tools"]:::tool
        R["Facebook Integration"]:::tool
    end

    %% Connections in Frontend
    A -->|"sendsRequest"| C
    B -->|"AJAXcall"| G
    C -->|"routesAPI"| G
    Q --> D
    D -->|"compiledBy"| E
    E -->|"produces"| F

    %% Connections in Backend & Database
    G -->|"invokes"| I
    G -->|"invokes"| J
    G -->|"invokes"| K
    G -->|"invokes"| L
    I -->|"CRUD"| N
    J -->|"CRUD"| N
    K -->|"CRUD"| N
    L -->|"CRUD"| N
    H -->|"updates"| N
    G -->|"readsConfig"| M
    O -->|"setsUp"| N
    P -->|"populates"| N
    G -->|"integratesWith"| R

    %% Styling Classes
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef model fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef asset fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef database fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef tool fill:#d1c4e9,stroke:#5e35b1,stroke-width:2px;

    %% Click Events
    click G "https://github.com/anasanzari/bullz-and-bears/tree/master/app/Http/Controllers"
    click H "https://github.com/anasanzari/bullz-and-bears/tree/master/app/Console/Commands"
    click I "https://github.com/anasanzari/bullz-and-bears/blob/master/app/Stock.php"
    click J "https://github.com/anasanzari/bullz-and-bears/blob/master/app/BoughtStock.php"
    click K "https://github.com/anasanzari/bullz-and-bears/blob/master/app/Transaction.php"
    click L "https://github.com/anasanzari/bullz-and-bears/blob/master/app/User.php"
    click M "https://github.com/anasanzari/bullz-and-bears/blob/master/config/bullz.php"
    click B "https://github.com/anasanzari/bullz-and-bears/tree/master/resources/src"
    click D "https://github.com/anasanzari/bullz-and-bears/tree/master/resources/assets/sass"
    click E "https://github.com/anasanzari/bullz-and-bears/blob/master/Gruntfile.js"
    click C "https://github.com/anasanzari/bullz-and-bears/blob/master/public/index.php"
    click O "https://github.com/anasanzari/bullz-and-bears/tree/master/database/migrations"
    click P "https://github.com/anasanzari/bullz-and-bears/tree/master/database/seeds"
```
