# my-crazy-lab/remixrun-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/my-crazy-lab/remixrun-boilerplate
- Repository: https://github.com/my-crazy-lab/remixrun-boilerplate

## Overview

##### Project type and purpose
- This is a full-stack, enterprise back-office (internal admin) application built on Remix.
- It provides user management, role-based access control (RBAC), action history, i18n, email reset, file upload, charts, and other UI components.
- Backend logic (authentication, session, mail, prom-client, data modeling) lives in the `app/services` folder; frontend UI uses React, Tailwind, Shadcn, charts, and custom hooks.

##### File structure
Top-level:
- `@/components` – Shared UI library (base chart primitives, btaskee design system, shadcn/ui).
- `app` – Core Remix source:
– `entry.client.tsx`, `entry.server.tsx` – Remix client/server entry points.
– `routes` – File-based routing for pages and nested routes.
– `services` – Server endpoints and data-access (authentication, mail, RBAC, MongoDB models, external API proxies, S3).
– `context`, `hooks`, `hoc`, `utils`, `constants`, `types` – State management, helpers, shared types.
– `app/__tests__` – Unit tests for services and routes.
- `public` – Static assets (locales JSON for i18n).
- `docker-compose.yml`, `Dockerfile` – Containerization.
- Configs – ESLint, Prettier, Jest, GitLab CI, Tailwind, Remix.

##### README
- Confirms TypeScript, Remix, i18n, RBAC, Jest tests, Docker support.
- Outlines code structure: `@` for UI, `app` for source, `public` for static, `test` & `build` for output/docs.
- Lists features: Authentication, Role-based access control, Action history, Internationalization.

##### Main components and their relationships
a. Components:
- Frontend / Client (browser): React + Remix app hydration – UI components, charts, forms.
- Remix Server (Node): SSR, routing, data loaders, action handlers.
- Services layer:
– Auth & session management (Remix Auth).
– Mail server (SMTP).
– Data models with MongoDB (users, roles, groups, permissions, isoCode, actionHistory).
– External API proxies (th, vn, id).
– S3 file storage.
– Prometheus metrics client.
- Database: MongoDB cluster.
- External services: SMTP mail provider, AWS S3, geolocation APIs (via proxy).
- DevOps: Docker, GitLab CI/CD.

b. Interactions:
- Browser → Remix Server via HTTP(S) requests (page navigation, form posts, JS API calls).
- Remix Server → Services layer (internal functions calling MongoDB, SMTP, S3, external APIs).
- Services layer ↔ MongoDB.
- Services layer → External APIs/S3/SMTP.
- Prometheus client instrumented inside server for metrics scraping.
- Remix Server → Browser – SSR HTML + hydration.

c. Architectural patterns / principles:
- File-based routing (Remix).
- Separation of concerns: UI vs. server logic vs. data access.
- SSR + CSR hybrid for performance and SEO.
- Centralized services layer for business logic.
- RBAC implemented in services + routes with guards.
- Monorepo-style UI library under `@/components`.

d. Key technologies:
- Remix (SSR + routing).
- React 18 + Shadcn UI + Tailwind CSS.
- TypeScript.
- Zustand (global state), React Hook Form, Lodash, Moment.js, TanStack Table.
- MongoDB, Mongoose-style model files.
- Jest + Testing Library for 100% coverage.
- Docker + Docker-Compose + GitLab CI/CD.

##### Details
- UI library (`@/components`) feeding into page routes.
- I18n JSON files under static assets.
- Unit tests and CI pipeline as side annotation if desired for completeness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser Client"]:::frontend
        Components["Shared UI Library (@/components)"]:::frontend
        entryClient["entry.client.tsx"]:::frontend
        entryServer["entry.server.tsx"]:::frontend
        Tailwind["tailwind.css"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Server["Remix Server"]:::backend

        subgraph "Routing & SSR Engine"
            direction TB
            Routes["File-based Routes"]:::backend
            SSR["SSR Engine/Hydration"]:::backend
        end

        subgraph "Services Layer"
            direction TB
            Auth["Auth Service"]:::service
            Session["Session Service"]:::service
            Passport["Passport Strategies"]:::service
            RBAC["RBAC Service"]:::service
            Mail["Mail Service"]:::service
            Prom["Prometheus Client"]:::service

            subgraph "API Proxies"
                direction TB
                ThAPI["Thailand Proxy"]:::service
                VnAPI["Vietnam Proxy"]:::service
                IdAPI["Indonesia Proxy"]:::service
            end

            subgraph "Data Models"
                direction TB
                Users["Users Model"]:::service
                Roles["Roles Model"]:::service
                Perms["Permissions Model"]:::service
                Groups["Groups Model"]:::service
                Hist["ActionHistory Model"]:::service
                ISO["ISO Codes Models"]:::service
            end

            S3["S3 File Storage"]:::service
            DotEnv["Dotenv Loader"]:::service
            Consts["Constants"]:::service
            HelpersSrv["Server Helpers"]:::service
            DbUtil["DB Connection"]:::service
        end
    end

    %% Data Stores & External
    DB["MongoDB Cluster"]:::database
    SMTP["SMTP Mail Provider"]:::external
    S3Cloud["AWS S3"]:::external
    GeoExt["External Geo APIs"]:::external

    %% Connections
    Browser -->|"HTTPS"| entryClient
    Browser -->|"HTTPS"| entryServer
    entryServer --> Server
    entryClient --> Browser
    Server --> Routes
    Server --> SSR
    Server --> Auth
    Server --> Session
    Server --> Passport
    Server --> RBAC
    Server --> Mail
    Server --> Prom
    Server --> ThAPI
    Server --> VnAPI
    Server --> IdAPI
    Server --> S3
    Server --> Users
    Server --> Roles
    Server --> Perms
    Server --> Groups
    Server --> Hist
    Server --> ISO
    Server --> DotEnv
    Server --> Consts
    Server --> HelpersSrv
    Server --> DbUtil

    %% Services to DB & External
    subgraph "Service Integrations"
        ServicesLayer(("Services Layer"))
        ServicesLayer --> DB
        ServicesLayer --> SMTP
        ServicesLayer --> S3Cloud
        ServicesLayer --> GeoExt
    end

    %% Click Events
    click Components "https://github.com/my-crazy-lab/remixrun-boilerplate/tree/main/@/components"
    click entryClient "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/entry.client.tsx"
    click entryServer "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/entry.server.tsx"
    click Routes "https://github.com/my-crazy-lab/remixrun-boilerplate/tree/main/app/routes"
    click Auth "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/auth.server.ts"
    click Session "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/session.server.ts"
    click Passport "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/passports.server.ts"
    click RBAC "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/role-base-access-control.server.ts"
    click Mail "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/mail.server.ts"
    click Prom "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/prometheus-client.server.ts"
    click ThAPI "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/api-proxy/th.server.ts"
    click VnAPI "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/api-proxy/vn.server.ts"
    click IdAPI "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/api-proxy/id.server.ts"
    click Users "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/model/users.server.ts"
    click Roles "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/model/roles.servers.ts"
    click Perms "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/model/permissions.server.ts"
    click Groups "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/model/groups.server.ts"
    click Hist "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/model/actionHistory.server.ts"
    click ISO "https://github.com/my-crazy-lab/remixrun-boilerplate/tree/main/app/services/model/isoCode"
    click S3 "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/utils/s3.server.ts"
    click DotEnv "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/dotenv.server.ts"
    click Consts "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/constants.server.ts"
    click HelpersSrv "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/services/helpers.server.ts"
    click DbUtil "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/utils/db.server.ts"
    click Tailwind "https://github.com/my-crazy-lab/remixrun-boilerplate/blob/main/app/tailwind.css"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0066CC,color:#000
    classDef backend fill:#D6F5D6,stroke:#228B22,color:#000
    classDef service fill:#CCFFE5,stroke:#00A66C,color:#000
    classDef database fill:#FFF0B3,stroke:#D4A017,color:#000
    classDef external fill:#FFE6CC,stroke:#FF8C00,color:#000
```
