# mariocodev/ng-dragon-ball-api architecture

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

- Interactive diagram: https://gitdiagram.com/mariocodev/ng-dragon-ball-api
- Repository: https://github.com/mariocodev/ng-dragon-ball-api

## Overview

##### Project Type and Purpose
- This is an Angular-based web application (with optional server-side rendering via Express).
- It serves as a responsive SPA that consumes the external Dragon Ball API to list and filter characters, and display details in a modal.
- Key features: reactive filters, dark/light theme toggling, SSR entry point (server.ts + main.server.ts), and proxy configuration for API calls in development.

##### File Structure Analysis
- Top level
- angular.json, package.json / package-lock.json → Angular CLI configuration and dependencies.
- server.ts, src/main.server.ts → Express server bootstrap + Angular Universal SSR.
- proxy.config*.json → Local API proxy for development.
- public/ → Static assets served by Express.
- src/
- src/main.ts → Browser app entry point.
- src/app/
– app.component.*, app.routes.ts → Root component and client routing.
– app.config.ts / app.config.server.ts → Environment-specific configuration.
– pages/character-details → Feature component for character detail view.
– shared/models → Data interfaces for API responses.
– shared/services/dragon-ball.service.ts → HTTP client for remote API.
- Tailwind + Flowbite styling via tailwind.config.js and global styles.scss.
- Environment files under src/environments for dev/prod builds.

##### README Insights
- Frontend tech stack: Angular 18, Tailwind CSS + Flowbite, npm.
- Dev flow: nvm → Node.js → Angular CLI → npm scripts for start:uat, build:dev/uat/prod.
- Environments: dev, uat (staging), prod.
- Emphasis on proxy usage and environment flags.

##### Components
a. Client Tier
- Browser (User Interface)
- Angular SPA (app shell + client-side routing)
- Reactive Forms module for filters
- Theme toggler
b. Server Tier (optional SSR)
- Express server (server.ts)
- Angular Universal (main.server.ts)
- Static asset handler (public/)
c. External Services
- Dragon Ball API (https://web.dragonball-api.com)
- Proxy layer (/api → remote) for CORS during dev
d. Build & Deployment
- npm scripts (start:uat, build:prod, etc.)
- Environment configurations (src/environments/*.ts)
- TailwindCSS pipeline

##### Relationships & Interactions
- Browser → Express (SSR) on initial page load → Angular Universal renders HTML.
- Browser (hydrated Angular) → DragonBallService → HTTP GET /api/… → Proxy → Dragon Ball API → JSON Response → UI.
- User filters input → Reactive Forms → DragonBallService calls → UI update.
- Environment flags toggle API endpoints and production optimizations.

##### Architectural Patterns & Principles
- SPA with optional SSR (Universal) for SEO / performance
- Modular feature segregation (pages vs. shared)
- Service-based API access (single responsibility)
- Environment-driven builds (dev/uat/prod)
- Utility-first CSS (Tailwind + Flowbite)

##### Detailed Breakdown to Capture
- App Shell: app.component, routing module
- Feature Module: CharacterDetailsComponent
- Shared Layer: Models + DragonBallService
- Environment Configurator: app.config.ts vs. app.config.server.ts
- Build Pipeline: npm run build:dev/uat/prod → output hashing
- Deployment Targets: dev / uat / prod servers serving static assets or SSR
- Styling Engine: TailwindCSS + Flowbite

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Layer
    subgraph "Build & Deployment" 
        direction TB
        NPM["npm Scripts\n(start:uat, build:dev/uat/prod)"]:::build
        EnvClient["Environment Config (Client)"]:::build
        EnvServer["Environment Config (Server)"]:::build
        Tailwind["TailwindCSS Pipeline"]:::build
    end

    %% Server Tier (SSR)
    subgraph "Server Tier (SSR)" 
        direction TB
        Express["Express Server\n(server.ts)"]:::server
        Universal["Angular Universal\n(main.server.ts)"]:::server
        Static["Static Assets\n(public/)"]:::server
    end

    %% Client Tier
    subgraph "Client Tier (Browser)" 
        direction TB
        Browser["Browser (User UI)"]:::frontend
        subgraph "Angular SPA"
            direction TB
            Entry["SPA Entry Point\n(src/main.ts)"]:::frontend
            AppShell["App Shell\n(app.component.ts/html/scss)"]:::frontend
            Routing["Client Routing Module\n(app.routes.ts)"]:::frontend
            Feature["Character Details Component\n(character-details.*)"]:::frontend
            SharedSvc["DragonBallService\n(dragon-ball.service.ts)"]:::frontend
            Models["Shared Models\n(src/app/shared/models/)"]:::frontend
            Reactive["Reactive Forms"]:::frontend
            Theme["Theme Toggler"]:::frontend
            IndexHTML["Index HTML\n(src/index.html)"]:::frontend
        end
    end

    %% External
    subgraph "External Services"
        direction TB
        Proxy["API Proxy (dev)\n(proxy.config.example.json)"]:::external
        DragonAPI["Dragon Ball API\n(https://web.dragonball-api.com)"]:::external
    end

    %% Flows & Relationships
    NPM -->|uses| EnvClient
    NPM -->|uses| EnvServer
    NPM -->|runs| Tailwind
    EnvClient -->|configures| Entry
    EnvServer -->|configures| Universal

    Browser -->|initial GET HTML| Express
    Express -->|renders via| Universal
    Universal -->|serves HTML| Browser

    Browser -->|bootstrap| Entry
    Entry -->|loads| AppShell
    AppShell -->|routes| Routing
    Routing -->|renders| Feature
    AppShell -->|provides| Reactive
    AppShell -->|provides| Theme

    Feature -->|calls| SharedSvc
    SharedSvc -->|GET /api/...| Proxy
    Proxy -->|forwards| DragonAPI
    DragonAPI -->|JSON data| Proxy
    Proxy -->|responds| SharedSvc
    SharedSvc -->|updates UI| Feature

    Static -->|serves static| Browser

    %% Click Events
    click Entry "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/main.ts"
    click Express "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/server.ts"
    click Universal "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/main.server.ts"
    click AppShell "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.component.ts"
    click AppShell "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.component.html"
    click AppShell "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.component.scss"
    click Routing "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.routes.ts"
    click EnvClient "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.config.ts"
    click EnvClient "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/environments/environment.ts"
    click EnvServer "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.config.server.ts"
    click Feature "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/pages/character-details/character-details.component.ts"
    click Feature "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/pages/character-details/character-details.component.html"
    click Feature "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/pages/character-details/character-details.component.scss"
    click Models "https://github.com/mariocodev/ng-dragon-ball-api/tree/main/src/app/shared/models/"
    click SharedSvc "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/shared/services/dragon-ball.service.ts"
    click Proxy "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/proxy.config.example.json"
    click Static "https://github.com/mariocodev/ng-dragon-ball-api/tree/main/public/"
    click Tailwind "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/tailwind.config.js"
    click Tailwind "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/styles.scss"
    click NPM "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/angular.json"
    click NPM "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/package.json"
    click NPM "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/tsconfig.app.json"
    click NPM "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/tsconfig.json"
    click SharedSvc "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/shared/services/dragon-ball.service.spec.ts"
    click Feature "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/pages/character-details/character-details.component.spec.ts"
    click AppShell "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/app/app.component.spec.ts"
    click IndexHTML "https://github.com/mariocodev/ng-dragon-ball-api/blob/main/src/index.html"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef server fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C
    classDef build fill:#FFF3E0,stroke:#E65100,color:#E65100
```
