# buildtruck/frontendwebapps architecture

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

- Interactive diagram: https://gitdiagram.com/buildtruck/frontendwebapps
- Repository: https://github.com/buildtruck/frontendwebapps

## Overview

##### Project type and purpose
- This is a single-page front-end application built with Vue 3 and Vite.
- It implements a multi-role management dashboard (admin, manager, supervisor) that consumes RESTful APIs (real or mock) to manage configurations, incidents, machinery, materials, personnel, projects, reports, and stats.
- It’s deployed as static assets via Firebase Hosting and, for local development, can use a JSON-server backend (server/db.json).

##### File structure
- Top level:
- index.html, public/, style.css → static assets and entry point
- src/ → application source
- server/db.json → mock data for JSON-server
- firebase.json, .firebaserc, .firebase/ → Firebase Hosting configuration
- Inside src/:
- core/ → shared components, base services, HTTP & user-API service, admin sub-module
- auth/ → authentication service and login view
- context/ → feature-based subdirectories for each domain (configuration, documentation, incidents, machinery, materials, personnel, projects, reports, stats) and user-role modules (manager, supervisor) with their own views, layouts, router, models, and API services
- router/index.js → client-side routing
- i18n.js + locales/ → internationalization
- App.vue & main.js → root component and bootstrapping
- Configuration/build:
- package.json, vite.config.js → dependencies and build tooling
- .env → environment variables (API endpoints, auth keys)

##### README for additional insights
- Confirms Vue 3 + Vite stack
- Emphasizes script-setup SFCs and scaling guidance

a. Main components
- Client (Browser) running the Vue 3 SPA
- Firebase Hosting (static asset CDN)
- Development JSON-server (server/db.json) or external REST API
- Authentication service (custom auth-API or Firebase Auth if configured)
- i18n engine for localization
- Shared core services (HTTP, base, user-API)
- Feature modules (contexts + core/admin)
- Vue Router for navigation
b. Relationships & interactions
- Browser ←(HTTP GET)→ Firebase Hosting serves index.html + JS/CSS
- Browser → (Vue Router) → dynamic component / view loading from src/
- Components → (service calls via HTTP service) → JSON-server or external API
- Auth views/services manage sign-in, obtain auth token, attach to API calls
- i18n engine loads locale files, injects into components
c. Architectural patterns & design principles
- Feature-based modular architecture (“context” folders)
- Service-layer pattern: each feature’s API service wraps HTTP calls
- Shared Core module for cross-cutting concerns (UI controls, notification, HTTP wrapper)
- Composition API & script-setup SFCs for lightweight, maintainable components
d. Key technologies/frameworks
- Vue 3, Vue Router, Vite, Composition API
- JSON-server for local mock backend or external REST endpoints
- Firebase Hosting for deployment
- i18n via vue-i18n

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        FirebaseHosting(("Firebase Hosting")):::infra
        DevServer([Vite Dev Server]):::infra
    end

    %% Client Browser
    Browser(["Browser (Vue 3 SPA)"]):::app

    Browser -->|Serves static assets| FirebaseHosting
    Browser -->|Local dev| DevServer

    %% Presentation Tier
    subgraph "Presentation Tier" 
        direction TB
        MainJS["main.js"]:::app
        AppVue["App.vue"]:::app
        Router["Vue Router"]:::app
        PageNotFound["PageNotFound.vue"]:::app
        LoginView["login.component.vue"]:::app
    end

    Browser -->|Bootstraps| MainJS
    MainJS -->|Renders| AppVue
    AppVue -->|Uses| Router
    Router --> PageNotFound
    Router --> LoginView

    %% Internationalization
    subgraph "i18n Engine" 
        direction TB
        I18nCore["i18n.js"]:::service
        LocaleEN["en.json"]:::service
        LocaleES["es.json"]:::service
    end

    AppVue -->|Loads locales| I18nCore
    I18nCore --> LocaleEN
    I18nCore --> LocaleES

    %% Core Layer
    subgraph "Shared Core Layer" 
        direction TB
        BaseService["base.service.js"]:::core
        HTTPService["http.service.js"]:::core
        UserAPIService["user-api.service.js"]:::core
        AppButton["AppButton.vue"]:::core
        AppCard["AppCard.vue"]:::core
        AppInput["AppInput.vue"]:::core
        AppNotification["AppNotification.vue"]:::core
        AppTable["AppTable.vue"]:::core
        LocationInput["LocationInput.vue"]:::core
        LanguageSwitcher["language-switcher.component.vue"]:::core
    end

    AppVue -->|Imports| BaseService
    BaseService --> HTTPService
    HTTPService --> UserAPIService

    %% Core Admin Sub-module
    subgraph "Core Admin Module" 
        direction TB
        AdminDashboard["admin-dashboard.component.vue"]:::core
        AdminUser["admin-user.component.vue"]:::core
        AdminLayout["AdminLayout.vue"]:::core
        AdminEntity["admin.entity.js"]:::core
        AdminAPI["admin-api.service.js"]:::core
        AdminRoutes["admin.routes.js"]:::core
    end

    Router --> AdminRoutes
    AdminRoutes --> AdminLayout
    AdminLayout --> AdminDashboard
    AdminLayout --> AdminUser
    AdminAPI --> AdminEntity

    %% Feature Modules
    subgraph "Feature Modules" 
        direction TB
        Configuration["configuration/"]:::feature
        Documentation["documentation/"]:::feature
        Incidents["incidents/"]:::feature
        Machinery["machinery/"]:::feature
        Materials["materials/"]:::feature
        Personnel["personnel/"]:::feature
        Projects["projects/"]:::feature
        Reports["reports/"]:::feature
        Stats["stats/"]:::feature
    end

    HTTPService --> Configuration
    HTTPService --> Documentation
    HTTPService --> Incidents
    HTTPService --> Machinery
    HTTPService --> Materials
    HTTPService --> Personnel
    HTTPService --> Projects
    HTTPService --> Reports
    HTTPService --> Stats

    %% Role-based Modules
    subgraph "Role-based Modules" 
        direction TB
        Manager["manager/"]:::feature
        Supervisor["supervisor/"]:::feature
    end

    Router --> Manager
    Router --> Supervisor

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        JSONServer[(JSON-server db.json)]:::data
        ExternalAPI[(External REST API)]:::data
    end

    HTTPService -->|Fetch data| JSONServer
    HTTPService -->|Fetch data| ExternalAPI

    %% Click Events
    click MainJS "https://github.com/buildtruck/frontendwebapps/blob/main/src/main.js"
    click AppVue "https://github.com/buildtruck/frontendwebapps/blob/main/src/App.vue"
    click Router "https://github.com/buildtruck/frontendwebapps/blob/main/src/router/index.js"
    click PageNotFound "https://github.com/buildtruck/frontendwebapps/blob/main/src/views/PageNotFound.vue"
    click FirebaseHosting "https://github.com/buildtruck/frontendwebapps/blob/main/firebase.json"
    click FirebaseHosting "https://github.com/buildtruck/frontendwebapps/blob/main/.firebaserc"
    click FirebaseHosting "https://github.com/buildtruck/frontendwebapps/tree/main/.firebase/"
    click JSONServer "https://github.com/buildtruck/frontendwebapps/blob/main/server/db.json"
    click UserAPIService "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/services/user-api.service.js"
    click HTTPService "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/services/http.service.js"
    click BaseService "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/services/base.service.js"
    click AppButton "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/AppButton.vue"
    click AppCard "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/AppCard.vue"
    click AppInput "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/AppInput.vue"
    click AppNotification "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/AppNotification.vue"
    click AppTable "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/AppTable.vue"
    click LocationInput "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/LocationInput.vue"
    click LanguageSwitcher "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/components/language-switcher.component.vue"
    click AdminDashboard "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/components/admin-dashboard.component.vue"
    click AdminUser "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/components/admin-user.component.vue"
    click AdminLayout "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/layouts/AdminLayout.vue"
    click AdminEntity "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/models/admin.entity.js"
    click AdminAPI "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/services/admin-api.service.js"
    click AdminRoutes "https://github.com/buildtruck/frontendwebapps/blob/main/src/core/admin/router/admin.routes.js"
    click Configuration "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/configuration/"
    click Documentation "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/documentation/"
    click Incidents "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/incidents/"
    click Machinery "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/machinery/"
    click Materials "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/materials/"
    click Personnel "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/personnel/"
    click Projects "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/projects/"
    click Reports "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/reports/"
    click Stats "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/stats/"
    click Manager "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/manager/"
    click Supervisor "https://github.com/buildtruck/frontendwebapps/tree/main/src/context/supervisor/"
    click LoginView "https://github.com/buildtruck/frontendwebapps/blob/main/src/auth/views/login.component.vue"
    click I18nCore "https://github.com/buildtruck/frontendwebapps/blob/main/src/i18n.js"
    click LocaleEN "https://github.com/buildtruck/frontendwebapps/blob/main/src/locales/en.json"
    click LocaleES "https://github.com/buildtruck/frontendwebapps/blob/main/src/locales/es.json"

    %% Styles
    classDef app fill:#cce5ff,stroke:#004085,color:#004085
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef core fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef feature fill:#f1f1f1,stroke:#333333,color:#333333
    classDef data fill:#fdebd0,stroke:#ba4a00,color:#ba4a00
```
