# sdileep/epic-stack architecture

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

- Interactive diagram: https://gitdiagram.com/sdileep/epic-stack
- Repository: https://github.com/sdileep/epic-stack

## Overview

##### Project type and purpose
- This is a full-stack web application “starter kit” built on Remix + React + Prisma, an opinionated reference for shipping production-ready apps quickly.
- It provides a complete sample application—including authentication (username/password, OAuth, WebAuthn), user profiles, note-taking features, image storage, monitoring, caching, E2E tests, and deployment recipes.

##### File structure
- Top-level directories:
- app/ – the Remix-based frontend and server-side routes & React components
- server/ – custom server entry and tooling (e.g. dev server, monitoring)
- prisma/ – database schema, migrations, seeding
- tests/ – unit/E2E tests and fixtures
- docs/ – architecture decisions, guides, feature docs
- Key indicators:
- app/routes/ – URL-to-module mapping for SSR and data loaders
- app/components/ + app/utils/ – UI primitives and backend helpers (auth, email, cache, storage)
- prisma/schema.prisma – relational data model (SQLite or cloud DB)
- fly.toml + GitHub workflows – deployment on Fly.io via GitHub Actions

##### README
- Confirms it’s “The Epic Stack” opinionated starter for Epic Web apps.
- Points to documentation for auth, caching, deployment, image storage, testing, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Browser["Client (Browser)\n(Runs React)"]:::client
        UIComp["UI Components\napp/components"]:::client
        Styles["Tailwind CSS\napp/styles/tailwind.css"]:::client
        MonitoringClient["Client Monitoring\napp/utils/monitoring.client.ts"]:::external
    end

    %% Server Layer
    subgraph "Server Layer"
        RemixServer["Remix Server\nNode.js Runtime"]:::server
        Routing["Routing Module\napp/routes"]:::server
        EntryClient["Entry Client\napp/entry.client.tsx"]:::server
        EntryServer["Entry Server\napp/entry.server.tsx"]:::server
        Root["Root Component\napp/root.tsx"]:::server
        ServerRuntime["Server Runtime\nserver/index.ts"]:::server
        DevServer["Dev Server\nserver/dev-server.js"]:::server
        MonitoringServer["Server Monitoring Utils\nserver/utils/monitoring.ts"]:::server
        Session["Session Management\napp/utils/session.server.ts"]:::server
        Permissions["Permissions\napp/utils/permissions.server.ts"]:::server
    end

    %% Data Layer
    subgraph "Data Layer"
        DBUtil["DB Utils\napp/utils/db.server.ts"]:::data
        DB["Database\nprisma/schema.prisma"]:::data
        Migrations["Migrations\nprisma/migrations/"]:::data
        Seed["DB Seed\nprisma/seed.ts"]:::data
        Cache["Caching Layer\napp/utils/cache.server.ts"]:::data
        Storage["File Storage\napp/utils/storage.server.ts"]:::data
        Litefs["LiteFS Config\nother/litefs.yml"]:::data
    end

    %% External Services
    subgraph "External Services"
        OAuth["OAuth Providers\ngithub.server.ts"]:::external
        EmailServ["Email Service\napp/utils/email.server.ts"]:::external
        PasswordAPI["Pwned-Password API\ntests/mocks/pwned-passwords.ts"]:::external
        CI["CI/CD Pipeline\n.github/workflows/deploy.yml"]:::external
        Fly["Fly.io Config\nfly.toml"]:::external
        Docker["Dockerfile\nother/Dockerfile"]:::external
        Playwright["Playwright Config\nplaywright.config.ts"]:::external
        E2E["E2E Tests\ntests/e2e/"]:::external
    end

    %% Connections
    UIComp --> Browser
    Styles --> Browser
    Browser --> MonitoringClient
    Browser <-->|HTTP/HTTPS| RemixServer
    Browser -->|hydrate| EntryClient
    RemixServer --> Routing
    RemixServer --> EntryServer
    RemixServer --> Root
    RemixServer --> DBUtil
    DBUtil --> DB
    DBUtil --> Migrations
    DBUtil --> Seed
    RemixServer --> Cache
    RemixServer --> Storage
    Storage --> Litefs
    RemixServer --> Session
    RemixServer --> Permissions
    RemixServer --> OAuth
    RemixServer --> EmailServ
    RemixServer --> PasswordAPI
    RemixServer --> MonitoringServer
    MonitoringClient --> MonitoringServer
    CI --> RemixServer
    CI --> Fly
    CI --> Docker
    Fly --> RemixServer
    Playwright --> RemixServer
    Playwright --> PasswordAPI
    Playwright --> E2E

    %% Click Events
    click UIComp "https://github.com/sdileep/epic-stack/tree/main/app/components/"
    click Styles "https://github.com/sdileep/epic-stack/blob/main/app/styles/tailwind.css"
    click EntryClient "https://github.com/sdileep/epic-stack/blob/main/app/entry.client.tsx"
    click EntryServer "https://github.com/sdileep/epic-stack/blob/main/app/entry.server.tsx"
    click Root "https://github.com/sdileep/epic-stack/blob/main/app/root.tsx"
    click Routing "https://github.com/sdileep/epic-stack/tree/main/app/routes/"
    click ServerRuntime "https://github.com/sdileep/epic-stack/blob/main/server/index.ts"
    click DevServer "https://github.com/sdileep/epic-stack/blob/main/server/dev-server.js"
    click MonitoringServer "https://github.com/sdileep/epic-stack/blob/main/server/utils/monitoring.ts"
    click DBUtil "https://github.com/sdileep/epic-stack/blob/main/app/utils/db.server.ts"
    click DB "https://github.com/sdileep/epic-stack/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/sdileep/epic-stack/tree/main/prisma/migrations/"
    click Seed "https://github.com/sdileep/epic-stack/blob/main/prisma/seed.ts"
    click Storage "https://github.com/sdileep/epic-stack/blob/main/app/utils/storage.server.ts"
    click Litefs "https://github.com/sdileep/epic-stack/blob/main/other/litefs.yml"
    click OAuth "https://github.com/sdileep/epic-stack/blob/main/app/utils/providers/github.server.ts"
    click EmailServ "https://github.com/sdileep/epic-stack/blob/main/app/utils/email.server.ts"
    click PasswordAPI "https://github.com/sdileep/epic-stack/blob/main/tests/mocks/pwned-passwords.ts"
    click MonitoringClient "https://github.com/sdileep/epic-stack/blob/main/app/utils/monitoring.client.ts"
    click Cache "https://github.com/sdileep/epic-stack/blob/main/app/utils/cache.server.ts"
    click Session "https://github.com/sdileep/epic-stack/blob/main/app/utils/session.server.ts"
    click Permissions "https://github.com/sdileep/epic-stack/blob/main/app/utils/permissions.server.ts"
    click CI "https://github.com/sdileep/epic-stack/blob/main/.github/workflows/deploy.yml"
    click Fly "https://github.com/sdileep/epic-stack/blob/main/fly.toml"
    click Docker "https://github.com/sdileep/epic-stack/tree/main/other/Dockerfile"
    click Playwright "https://github.com/sdileep/epic-stack/blob/main/playwright.config.ts"
    click E2E "https://github.com/sdileep/epic-stack/tree/main/tests/e2e/"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef server fill:#E6FFE6,stroke:#28A745,color:#28A745
    classDef data fill:#FFF4E5,stroke:#D97706,color:#D97706
    classDef external fill:#F3E8FF,stroke:#6B21A8,color:#6B21A8
```
