# epicweb-dev/full-stack-foundations architecture

> Architecture diagram of the GitHub repository epicweb-dev/full-stack-foundations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/epicweb-dev/full-stack-foundations
- Repository: https://github.com/epicweb-dev/full-stack-foundations

## Overview

This project is a complex, multi‐exercise full‐stack workshop that “epicshop” is the base application and that is then extended and modified through a large number of isolated “exercises”. In other words, the workshop teaches modern full-stack web application development (with a focus on React, TypeScript, Node.js, and Remix) by having you work on various problems (such as routing, asset imports, error handling, scripting, SEO, forms/mutations, etc.) within self-contained subfolders in the “exercises” directory.

##### Main Components
a. Base Application ("epicshop") – This is the full-stack web application which includes key configuration files (e.g. Dockerfile, package.json, tsconfig.json, and Remix configuration) and serves as the “core” app.
c. Backend – Although not necessarily a separately hosted microservice, the server-side code is embedded in the “epicshop” and the various exercise apps. It contains API route definitions, “dev-server” components, and even database helper scripts (e.g. db.server.ts in several exercises).
d. Exercises Modules – Multiple directories under “exercises” represent different aspects of system functionality (styling, routing, loading, mutations, scripting, SEO, error handling, etc.). Each module is almost a variant of the base app, allowing students to work on isolated technical challenges.
e. Infrastructure & CI/CD – The project contains a GitHub workflows directory (for deployment), Dockerfiles (for containerization), and npm scripts to set up and run tests. These build and deployment scripts are important components of the overall system.

##### Relationships and Data Flow
a. The client (frontend, built with React/Remix) sends HTTP requests to the server endpoints.
b. The server components (Node-based back-end code) handle routing, API logic, error handling, and responses. In many exercise variants, this backend is “extended” or modified to explore specific technical challenges.
d. CI/CD pipelines (GitHub Actions) lead to automated testing and deployment (e.g., through the Docker container defined in epicshop/Dockerfile).

##### Architectural Patterns and Design Principles
a. Separation of concerns – the architecture clearly separates the rendering layer (React/Remix client side), the application logic layer (server functions and routes), and the modular exercise implementations.
b. Reusable and extensible design – the exercises folder illustrates how the base app can be modified to test different web application fundamentals.
c. Modern full-stack design – leveraging development tools (npx, npm scripts, environment integration with editors through EPICSHOP_EDITOR) and containerization (Docker) highlights current design patterns.

##### Relevant Technologies and Tools
a. Node.js, npm and TypeScript are clearly part of the development stack.
b. React, Remix, and Tailwind CSS (as shown in styling directories and frequent usage of remix.config.js and tailwind.config.ts) are used for the UI and styling.
c. Docker and GitHub Actions represent the deployment and CI/CD best practices.
d. Testing and development environments are shown through the consistent use of playwright configurations and various “build-server.ts” files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    A["User Browser"]:::client

    subgraph "Frontend Layer"
        FE["Frontend (React/Remix UI)"]:::frontend
        FE_Entry["Frontend Entry Points (epicshop.tsx, root.tsx)"]:::frontend
        PublicAssets["Public Assets"]:::asset
    end

    subgraph "Epicshop Core Application"
        EC["Epicshop Core"]:::core
        CoreBackend["Core Backend Scripts"]:::backend
    end

    subgraph "Exercises Modules"
        EX["Exercises (/exercises)"]:::exercise
        EX_Backend["Exercise Backend"]:::backend
        EX_Routing["Exercise: Routing"]:::exercise
        EX_Styling["Exercise: Styling"]:::exercise
        EX_Loading["Exercise: Loading"]:::exercise
        EX_Mutations["Exercise: Mutations"]:::exercise
        EX_SEO["Exercise: SEO & Error Handling"]:::exercise
    end

    subgraph "CI/CD & Infrastructure"
        CI["CI/CD (GitHub Actions)"]:::infrastructure
        Docker["Docker Build"]:::infrastructure
        RootScripts["Project Root Scripts & Configs"]:::infrastructure
    end

    %% Connections
    A -->|"sends_request"| FE
    FE -->|"initializes"| FE_Entry
    FE_Entry -->|"loads_core_app"| EC
    FE -->|"serves_assets"| PublicAssets
    EC -->|"runs_backend"| CoreBackend
    EC -->|"extended_by"| EX
    EX -->|"has_backend_extensions"| EX_Backend
    EX -->|"handles_routing"| EX_Routing
    EX -->|"applies_styling"| EX_Styling
    EX -->|"loads_data"| EX_Loading
    EX -->|"executes_mutations"| EX_Mutations
    EX -->|"manages_seo_error"| EX_SEO
    EC -->|"integrates_CI"| CI
    CI -->|"triggers_build"| Docker
    CI -->|"verifies_configs"| RootScripts

    %% Click Events
    click EC "https://github.com/epicweb-dev/full-stack-foundations/tree/main//epicshop"
    click FE_Entry "https://github.com/epicweb-dev/full-stack-foundations/blob/main/exercises/01.styling/01.problem.public-links/app/epicshop.tsx"
    click PublicAssets "https://github.com/epicweb-dev/full-stack-foundations/tree/main/exercises/01.styling/01.problem.public-links/public"
    click EX "https://github.com/epicweb-dev/full-stack-foundations/tree/main//exercises"
    click EX_Backend "https://github.com/epicweb-dev/full-stack-foundations/tree/main/exercises/01.styling/01.problem.public-links/server"
    click CI "https://github.com/epicweb-dev/full-stack-foundations/blob/main/.github/workflows/deploy.yml"
    click Docker "https://github.com/epicweb-dev/full-stack-foundations/tree/main//epicshop/Dockerfile"
    click RootScripts "https://github.com/epicweb-dev/full-stack-foundations/blob/main//package.json"

    %% Styles
    classDef client fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef backend fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
    classDef exercise fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
    classDef asset fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef infrastructure fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
```
