# jackblue19/juice-shop-fork architecture

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

- Interactive diagram: https://gitdiagram.com/jackblue19/juice-shop-fork
- Repository: https://github.com/jackblue19/juice-shop-fork

## Overview

##### Project Type and Purpose
- OWASP Juice Shop is a full-stack, intentionally vulnerable web application used for security training, CTFs, and tool testing.
- It consists of an Angular SPA frontend, a Node.js/Express REST/API backend, and a data layer (MongoDB or in-memory JSON store), all of which can be run locally, in Docker, or via Vagrant.

##### File Structure Analysis
- Top-level “frontend” directory holds the Angular application (components, services, assets, environments, build config).
- Top-level server files (server.ts, Dockerfile, routes/, models/, lib/, data/) implement the Express app, business logic, data access, static file serving, WebSocket events, and startup routines.
- “data/” contains static YAML/JSON challenge definitions, chat-bot training data, and database connection code.
- “models/” defines TypeScript interfaces for domain objects (User, Challenge, Basket, etc.).
- “routes/” holds Express route modules mapping URL endpoints to controllers.
- DevOps configs (docker-compose.test.yml, .github/workflows/*, .gitlab-ci.yml, Vagrantfile) support CI/CD, testing, and multi-environment deployment.

##### README Insights
- Describes a containerized, cross-platform setup via Docker, Vagrant, or direct Node.js run.
- Mentions OWASP Top 10 vulnerabilities coverage and a companion guide for architecture overview.
- Emphasizes build/test pipelines (npm, Grunt, Cypress E2E, Jest/Mocha) and multiple deployment methods.

a. Main Components
- Client Tier: Angular SPA loaded in browser.
- API Layer: Express.js server exposing REST endpoints + WebSocket channel.
- Data Persistence: MongoDB (or built-in JSON store) for user/challenge data; filesystem for uploads/FTP.
- Static Assets Server: Express static middleware serves Angular bundle, images, legal, tutorial pages, and FTP quarantine.
- External Services: OAuth/OpenID provider, payment gateways, external chat-bot API, optionally SMTP or SMS.
- DevOps: Docker engine, CI/CD pipelines, Vagrant VM, monitoring (Grafana).

b. Relationships and Interactions
- Browser ↔️ Angular SPA: renders UI, invokes HTTP/WS to backend.
- Angular → Express REST API: JSON over HTTP for data CRUD and challenge interactions.
- Angular ← WebSocket: real-time “challenge solved” or notification events.
- Express → MongoDB: persistence layer for all domain entities (users, orders, challenges).
- Express → File System: store/retrieve user uploads, logs, FTP quarantine.
- Express → External OAuth/Payment: API calls for login, token sale, premium rewards.
- CI/CD → Docker Registry: automated build/test push for containers.

c. Architectural Patterns and Principles
- Layered (Presentation / Service / Data Access) on the server side.
- Modular routing in Express: one file per resource endpoint.
- Dependency Injection in Angular (Services → Components).
- Static content served alongside dynamic API in a monolithic Node.js process.
- Configuration‐driven startup routines validating preconditions and customizing behavior.

d. Key Technologies, Frameworks, Libraries
- Frontend: Angular, TypeScript, RxJS, Webpack, StyleLint, ESLint, Cypress for E2E tests.
- Backend: Node.js, Express.js, TypeScript, Mongoose or custom JSON store, WS or socket.io for realtime.
- DevOps: Docker, docker-compose, GitHub Actions/GitLab CI, Vagrant.
- Monitoring: Grafana dashboard, custom metrics endpoint.
- Security tooling: ZAP rules, code-fix snippets, CSAF metadata.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Client Tier (Browser)" 
        direction TB
        AngularSPA["Angular SPA"]:::frontend
        WebSocketClient["WebSocket Client Service"]:::frontend
    end

    AngularSPA -->|"HTTP/JSON (CRUD, Challenges)"| API
    AngularSPA -->|"WebSocket"| WSBackend
    WebSocketClient -->|"WebSocket"| WSBackend

    %% API Layer
    subgraph "API Layer (Node.js/Express)" 
        direction TB
        API["Express REST API"]:::backend
        WSBackend["WebSocket Channel"]:::backend
        Startup["Startup Routines"]:::backend
        Routes["Route Modules"]:::backend
        BusinessLogic["Business Logic & Utilities"]:::backend
    end

    Startup -->|init config, register WS| Routes
    Startup -->|init config| BusinessLogic
    Routes -->|invoke| BusinessLogic
    BusinessLogic -->|uses| DataStores

    %% Data Persistence
    subgraph "Data Persistence" 
        direction TB
        MongoDB["MongoDB"]:::datastore
        JSONStore["JSON Store & Cache"]:::datastore
        FileSystem["File System (uploads, logs, FTP quarantine)"]:::datastore
    end

    API -->|"TCP/MongoDB"| MongoDB
    API -->|"In-memory JSON"| JSONStore
    API -->|"FS I/O"| FileSystem

    %% Static Asset Serving
    API -->|"Serves Angular bundle, assets"| StaticAssets["Static Asset Server"]:::backend
    StaticAssets -->|"reads from"| dataStatic

    %% External Integrations
    subgraph "External Integrations" 
        direction TB
        OAuth["OAuth/OpenID & Payment"]:::external
        Chatbot["Chat-Bot API"]:::external
    end

    API -->|"HTTP/S"| OAuth
    API -->|"HTTP/S"| Chatbot

    %% Monitoring
    API -->|"METRICS"| Metrics["Monitoring Endpoint"]:::external

    %% DevOps & Deployment
    subgraph "DevOps & Deployment" 
        direction TB
        Docker["Docker & Compose"]:::devops
        CICD["CI/CD Pipelines"]:::devops
        Vagrant["Vagrant VM"]:::devops
        Grafana["Grafana Dashboard"]:::external
    end

    API -.->|build/test→registry| Docker
    Docker -.->|run| API
    CICD -.->|trigger builds| Docker
    Vagrant -.->|provisions| API
    Metrics -->|"scrapes"| Grafana

    %% Testing Harness
    subgraph "Testing Harness" 
        direction TB
        API_Tests["API Unit/Integration Tests"]:::test
        E2E["Cypress E2E Tests"]:::test
    end

    API_Tests -->|HTTP/JSON| API
    E2E -->|Browser Simulation| AngularSPA

    %% Click Events
    click AngularSPA "https://github.com/jackblue19/juice-shop-fork/tree/master/frontend/"
    click WebSocketClient "https://github.com/jackblue19/juice-shop-fork/blob/master/frontend/src/app/Services/socket-io.service.ts"
    click API "https://github.com/jackblue19/juice-shop-fork/blob/master/server.ts"
    click Routes "https://github.com/jackblue19/juice-shop-fork/tree/master/routes/"
    click BusinessLogic "https://github.com/jackblue19/juice-shop-fork/tree/master/lib/"
    click Startup "https://github.com/jackblue19/juice-shop-fork/tree/master/lib/startup/"
    click MongoDB "https://github.com/jackblue19/juice-shop-fork/blob/master/data/mongodb.ts"
    click JSONStore "https://github.com/jackblue19/juice-shop-fork/blob/master/data/datacreator.ts"
    click JSONStore "https://github.com/jackblue19/juice-shop-fork/blob/master/data/datacache.ts"
    click models "https://github.com/jackblue19/juice-shop-fork/tree/master/models/"
    click StaticAssets "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/angular.ts"
    click StaticAssets "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/fileServer.ts"
    click dataStatic "https://github.com/jackblue19/juice-shop-fork/tree/master/data/static/"
    click registerWS "https://github.com/jackblue19/juice-shop-fork/blob/master/lib/startup/registerWebsocketEvents.ts"
    click OAuth "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/authenticatedUsers.ts"
    click OAuth "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/login.ts"
    click OAuth "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/premiumReward.ts"
    click Chatbot "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/chatbot.ts"
    click Chatbot "https://github.com/jackblue19/juice-shop-fork/blob/master/data/static/botDefaultTrainingData.json"
    click quarantine "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/quarantineServer.ts"
    click quarantine "https://github.com/jackblue19/juice-shop-fork/tree/master/ftp/quarantine/"
    click Metrics "https://github.com/jackblue19/juice-shop-fork/blob/master/routes/metrics.ts"
    click Grafana "https://github.com/jackblue19/juice-shop-fork/blob/master/monitoring/grafana-dashboard.json"
    click Docker "https://github.com/jackblue19/juice-shop-fork/tree/master/Dockerfile"
    click Docker "https://github.com/jackblue19/juice-shop-fork/blob/master/docker-compose.test.yml"
    click CICD "https://github.com/jackblue19/juice-shop-fork/tree/master/.github/workflows/"
    click CICD "https://github.com/jackblue19/juice-shop-fork/blob/master/.gitlab-ci.yml"
    click Vagrant "https://github.com/jackblue19/juice-shop-fork/tree/master/vagrant/Vagrantfile"
    click Vagrant "https://github.com/jackblue19/juice-shop-fork/blob/master/vagrant/bootstrap.sh"
    click API_Tests "https://github.com/jackblue19/juice-shop-fork/tree/master/test/api/"
    click API_Tests "https://github.com/jackblue19/juice-shop-fork/tree/master/test/server/"
    click E2E "https://github.com/jackblue19/juice-shop-fork/tree/master/test/cypress/e2e/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef devops fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef test fill:#f5c6cb,stroke:#721c24,color:#721c24
```
