# hf1nacl/mailbox-demo architecture

> Architecture diagram of the GitHub repository hf1nacl/mailbox-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hf1nacl/mailbox-demo
- Repository: https://github.com/hf1nacl/mailbox-demo

## Overview

1. **What this repo is**
   - A template mail client built with **Ionic + Vue 3 + TypeScript**, designed to run as a **responsive web app** and as an **Android app via Capacitor**.
   - The product boundary is clear: it is a front-end demo/shell for a mailbox UI, not a full backend-connected mail system.

2. **Top-level application flow**
   - The browser entry starts at `index.html` and `src/main.ts`, which boot the Vue app.
   - `src/App.vue` and `src/layouts/MainLayout.vue` provide the main shell, while `src/router/index.ts` routes into the single visible page (`src/views/HomePage.vue`).

3. **Platform adaptation boundary**
   - The app has explicit branching for **web vs mobile/Android**.
   - `src/composables/capacitor.ts` and `src/composables/isDesktop.ts` are the main decision points that influence which UI variant gets rendered.
   - This is not just CSS responsiveness; it is a component-level split between platform-specific implementations.

4. **Responsive UI subsystem**
   - The app is decomposed into paired variants:
     - `src/components/app/sidebar/SidebarWeb.vue` and `SidebarMobile.vue`
     - `src/components/mailbox/MailboxWeb.vue` and `MailboxMobile.vue`
     - `src/components/mailbox/web/WebItem.vue` and `src/components/mailbox/mobile/MobileItem.vue`
   - `src/components/app/AppHeader.vue` and `AppSidebar.vue` sit above these variants and compose the page shell.

5. **Mailbox state and interactions**
   - The mailbox behavior appears local and demo-oriented, centered in `src/composables/useMails.ts`.
   - The readme indicates the app supports interaction for **read/unread**, **favorite**, and **selected** states.
   - This makes the mailbox a client-side state subsystem rather than a server-backed domain model.

6. **Mock data and offline demo layer**
   - Mock email content lives in `src/mocks/mails.ts`.
   - Request interception is set up with **Mock Service Worker** through `src/mocks/browser.ts` and `src/mocks/handlers.ts`, with the worker asset in `public/mockServiceWorker.js`.
   - The readme and `src/config/env.ts` indicate mocks can be enabled/disabled via environment configuration, so the data source can be switched without changing the UI.

7. **Configuration and feature flags**
   - `src/config/env.ts` centralizes environment-driven behavior, likely including whether mock mail data is active.
   - `src/config/sidebar.ts` and `src/config/sidebarWeb.ts` hold platform-specific navigation/sidebar definitions, reinforcing the web/mobile split at the config layer.

8. **Styling and visual system**
   - Styling is split between `src/theme/tailwind.css` and `src/theme/variables.css`.
   - This suggests a mix of utility-based styling and Ionic theme variables for platform-consistent UI, with layout controlled through the component tree rather than a separate design system package.

9. **Native Android container**
   - The `android/` directory is a full **Capacitor Android project**, including `MainActivity.java`, manifest, resources, Gradle files, and app packaging assets.
   - In architecture terms, Android is a thin native host that embeds the built web application rather than a separate native codebase.

10. **Build and runtime toolchain**
   - The front end is built with **Vite** (`vite.config.ts`) and managed with npm (`package.json`, `package-lock.json`).
   - Capacitor configuration (`capacitor.config.ts`) connects the web build to the Android shell.
   - The project is set up for local dev with `ionic serve` and for Android sync/build through Capacitor.

11. **Testing and validation boundaries**
   - End-to-end tests are under `tests/e2e/` and use **Cypress**.
   - Unit tests live under `tests/unit/`.
   - This gives the repo two separate validation layers: UI behavior in a browser-like environment and smaller unit-level checks.

12. **Delivery/deployment**
   - `.github/workflows/deploy.yml` indicates automated deployment is part of the repo’s lifecycle.
   - The live demo mentioned in the readme suggests the web build is intended to be published separately from the Android package.

13. **Important architectural takeaway for diagrams**
   - The cleanest diagram is: **Vue/Ionic UI shell → platform detection/config → web/mobile component variants → mailbox state/composables → mock data/MSW or future backend → Android Capacitor host for native packaging**.
   - The main boundary to emphasize is that the app’s “backend” is currently a **mocking layer**, and the main variability is **platform-specific presentation**, not domain complexity.

Main entry points: [`src/views/HomePage.vue`](https://github.com/hf1nacl/mailbox-demo/blob/master/src/views/HomePage.vue) (Home page), [`src/composables/useMails.ts`](https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/useMails.ts) (useMails), [`src/components/app/AppSidebar.vue`](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/AppSidebar.vue) (App sidebar), [`src/components/mailbox/MailboxWeb.vue`](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/MailboxWeb.vue) (Mailbox web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Frontend app"]
  node_n_index["index.html<br/>entry<br/>[index.html]"]
  node_n_main["main.ts<br/>bootstrap<br/>[main.ts]"]
  node_n_app["App.vue<br/>shell<br/>[App.vue]"]
  node_n_layout["Main layout<br/>[MainLayout.vue]"]
  node_n_router["Router<br/>routing<br/>[index.ts]"]
  node_n_home["Home page<br/>view<br/>[HomePage.vue]"]
  node_n_header["App header<br/>ui shell<br/>[AppHeader.vue]"]
  node_n_sidebar_shell["App sidebar<br/>ui shell<br/>[AppSidebar.vue]"]
end

subgraph group_g_platform["Platform split"]
  node_n_capacitor["Capacitor<br/>platform bridge<br/>[capacitor.ts]"]
  node_n_isdesktop["Desktop check<br/>platform switch<br/>[isDesktop.ts]"]
  node_n_sidebar_web["Sidebar web<br/>sidebar variant<br/>[SidebarWeb.vue]"]
  node_n_sidebar_mobile["Sidebar mobile<br/>sidebar variant<br/>[SidebarMobile.vue]"]
end

subgraph group_g_mailbox["Mailbox UI"]
  node_n_mailbox_web["Mailbox web<br/>mailbox variant<br/>[MailboxWeb.vue]"]
  node_n_mailbox_mobile["Mailbox mobile<br/>mailbox variant<br/>[MailboxMobile.vue]"]
  node_n_webitem["Web item<br/>mail row<br/>[WebItem.vue]"]
  node_n_mobileitem["Mobile item<br/>mail row<br/>[MobileItem.vue]"]
  node_n_usemails["useMails<br/>mail state<br/>[useMails.ts]"]
end

subgraph group_g_data["Mock data"]
  node_n_env["Env config<br/>configuration<br/>[env.ts]"]
  node_n_mails["Mock mails<br/>fixture data<br/>[mails.ts]"]
  node_n_msw["MSW worker<br/>mocking<br/>[browser.ts]"]
  node_n_handlers["Mock handlers<br/>mocking<br/>[handlers.ts]"]
end

subgraph group_g_native["Android host"]
  node_n_android["Android app<br/>native host<br/>[MainActivity.java]"]
end

subgraph group_g_tooling["Tooling"]
  node_n_vite["Vite<br/>build tool<br/>[vite.config.ts]"]
  node_n_cypress["Cypress<br/>e2e tests<br/>[cypress.config.ts]"]
  node_n_deploy["Deploy flow<br/>ci pipeline<br/>[deploy.yml]"]
end

node_n_index -->|"loads"| node_n_main
node_n_main -->|"mounts"| node_n_app
node_n_app -->|"uses"| node_n_layout
node_n_layout -->|"hosts"| node_n_router
node_n_router -->|"routes to"| node_n_home
node_n_home -->|"composes"| node_n_header
node_n_home -->|"composes"| node_n_sidebar_shell
node_n_home -->|"shows"| node_n_mailbox_web
node_n_home -->|"shows"| node_n_mailbox_mobile
node_n_sidebar_shell -->|"selects"| node_n_sidebar_web
node_n_sidebar_shell -->|"selects"| node_n_sidebar_mobile
node_n_mailbox_web -->|"renders"| node_n_webitem
node_n_mailbox_mobile -->|"renders"| node_n_mobileitem
node_n_mailbox_web -->|"reads state"| node_n_usemails
node_n_mailbox_mobile -->|"reads state"| node_n_usemails
node_n_usemails -->|"seeds"| node_n_mails
node_n_usemails -->|"checks"| node_n_env
node_n_msw -->|"registers"| node_n_handlers
node_n_handlers -->|"serves"| node_n_mails
node_n_env -->|"enables"| node_n_msw
node_n_capacitor -->|"influences"| node_n_isdesktop
node_n_android -->|"hosts"| node_n_capacitor
node_n_vite -->|"builds"| node_n_main
node_n_cypress -->|"tests"| node_n_home
node_n_deploy -->|"publishes"| node_n_vite

click node_n_index "https://github.com/hf1nacl/mailbox-demo/blob/master/index.html"
click node_n_main "https://github.com/hf1nacl/mailbox-demo/blob/master/src/main.ts"
click node_n_app "https://github.com/hf1nacl/mailbox-demo/blob/master/src/App.vue"
click node_n_layout "https://github.com/hf1nacl/mailbox-demo/blob/master/src/layouts/MainLayout.vue"
click node_n_router "https://github.com/hf1nacl/mailbox-demo/blob/master/src/router/index.ts"
click node_n_home "https://github.com/hf1nacl/mailbox-demo/blob/master/src/views/HomePage.vue"
click node_n_header "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/AppHeader.vue"
click node_n_sidebar_shell "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/AppSidebar.vue"
click node_n_capacitor "https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/capacitor.ts"
click node_n_isdesktop "https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/isDesktop.ts"
click node_n_sidebar_web "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/sidebar/SidebarWeb.vue"
click node_n_sidebar_mobile "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/sidebar/SidebarMobile.vue"
click node_n_mailbox_web "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/MailboxWeb.vue"
click node_n_mailbox_mobile "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/MailboxMobile.vue"
click node_n_webitem "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/web/WebItem.vue"
click node_n_mobileitem "https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/mobile/MobileItem.vue"
click node_n_usemails "https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/useMails.ts"
click node_n_env "https://github.com/hf1nacl/mailbox-demo/blob/master/src/config/env.ts"
click node_n_mails "https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/mails.ts"
click node_n_msw "https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/browser.ts"
click node_n_handlers "https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/handlers.ts"
click node_n_android "https://github.com/hf1nacl/mailbox-demo/blob/master/android/app/src/main/java/hf1nacl/mailboxdemo/vue/MainActivity.java"
click node_n_vite "https://github.com/hf1nacl/mailbox-demo/blob/master/vite.config.ts"
click node_n_cypress "https://github.com/hf1nacl/mailbox-demo/blob/master/cypress.config.ts"
click node_n_deploy "https://github.com/hf1nacl/mailbox-demo/blob/master/.github/workflows/deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_index,node_n_main,node_n_app,node_n_layout,node_n_router,node_n_home,node_n_header,node_n_sidebar_shell toneBlue
class node_n_capacitor,node_n_isdesktop,node_n_sidebar_web,node_n_sidebar_mobile toneAmber
class node_n_mailbox_web,node_n_mailbox_mobile,node_n_webitem,node_n_mobileitem,node_n_usemails toneMint
class node_n_env,node_n_mails,node_n_msw,node_n_handlers toneRose
class node_n_android toneIndigo
class node_n_vite,node_n_cypress,node_n_deploy toneTeal
```

## Components

### Frontend app

Vue/Ionic web application shell and page flow

- [index.html](https://github.com/hf1nacl/mailbox-demo/blob/master/index.html): entry · Browser entry point · `index.html`
- [main.ts](https://github.com/hf1nacl/mailbox-demo/blob/master/src/main.ts): bootstrap · Creates and mounts the Vue app · `src/main.ts`
- [App.vue](https://github.com/hf1nacl/mailbox-demo/blob/master/src/App.vue): shell · Top-level application component · `src/App.vue`
- [Main layout](https://github.com/hf1nacl/mailbox-demo/blob/master/src/layouts/MainLayout.vue): layout · Primary page shell and content frame · `src/layouts/MainLayout.vue`
- [Router](https://github.com/hf1nacl/mailbox-demo/blob/master/src/router/index.ts): routing · Routes into the visible page · `src/router/index.ts`
- [Home page](https://github.com/hf1nacl/mailbox-demo/blob/master/src/views/HomePage.vue): view · Single main page for the demo · `src/views/HomePage.vue`
- [App header](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/AppHeader.vue): ui shell · Top-level app chrome · `src/components/app/AppHeader.vue`
- [App sidebar](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/AppSidebar.vue): ui shell · Sidebar composition boundary · `src/components/app/AppSidebar.vue`

### Platform split

Web vs mobile adaptation boundaries

- [Capacitor](https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/capacitor.ts): platform bridge · Detects and adapts to native runtime · `src/composables/capacitor.ts`
- [Desktop check](https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/isDesktop.ts): platform switch · Chooses desktop or mobile presentation · `src/composables/isDesktop.ts`
- [Sidebar web](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/sidebar/SidebarWeb.vue): sidebar variant · Web sidebar implementation · `src/components/app/sidebar/SidebarWeb.vue`
- [Sidebar mobile](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/app/sidebar/SidebarMobile.vue): sidebar variant · Mobile sidebar implementation · `src/components/app/sidebar/SidebarMobile.vue`

### Mailbox UI

Mailbox presentation and local interaction state

- [Mailbox web](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/MailboxWeb.vue): mailbox variant · Web mailbox list and interactions · `src/components/mailbox/MailboxWeb.vue`
- [Mailbox mobile](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/MailboxMobile.vue): mailbox variant · Mobile mailbox list and interactions · `src/components/mailbox/MailboxMobile.vue`
- [Web item](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/web/WebItem.vue): mail row · Desktop mailbox row component · `src/components/mailbox/web/WebItem.vue`
- [Mobile item](https://github.com/hf1nacl/mailbox-demo/blob/master/src/components/mailbox/mobile/MobileItem.vue): mail row · Mobile mailbox row component · `src/components/mailbox/mobile/MobileItem.vue`
- [useMails](https://github.com/hf1nacl/mailbox-demo/blob/master/src/composables/useMails.ts): mail state · Client-side mailbox state and actions · `src/composables/useMails.ts`

### Mock data

Offline demo data and request interception

- [Env config](https://github.com/hf1nacl/mailbox-demo/blob/master/src/config/env.ts): configuration · Environment-driven feature toggles · `src/config/env.ts`
- [Mock mails](https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/mails.ts): fixture data · Offline demo mailbox content · `src/mocks/mails.ts`
- [MSW worker](https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/browser.ts): mocking · Browser request interception setup · `src/mocks/browser.ts`
- [Mock handlers](https://github.com/hf1nacl/mailbox-demo/blob/master/src/mocks/handlers.ts): mocking · Mock mail request handlers · `src/mocks/handlers.ts`

### Android host

Capacitor-wrapped native Android shell

- [Android app](https://github.com/hf1nacl/mailbox-demo/blob/master/android/app/src/main/java/hf1nacl/mailboxdemo/vue/MainActivity.java): native host · Capacitor Android packaging and runtime · `android/app/src/main/java/hf1nacl/mailboxdemo/vue/MainActivity.java`

### Tooling

Build, test, and deployment pipeline

- [Vite](https://github.com/hf1nacl/mailbox-demo/blob/master/vite.config.ts): build tool · Frontend build and dev server · `vite.config.ts`
- [Cypress](https://github.com/hf1nacl/mailbox-demo/blob/master/cypress.config.ts): e2e tests · End-to-end validation suite · `cypress.config.ts`
- [Deploy flow](https://github.com/hf1nacl/mailbox-demo/blob/master/.github/workflows/deploy.yml): ci pipeline · Automated deployment workflow · `.github/workflows/deploy.yml`

## Connections

- index.html → main.ts: loads · Browser entry bootstraps the app
- main.ts → App.vue: mounts · Vue app root is created and mounted
- App.vue → Main layout: uses · App delegates page framing to the main layout
- Main layout → Router: hosts · Layout contains routed content
- Router → Home page: routes to · Main route resolves to the home page
- Home page → App header: composes · Home page includes top app chrome
- Home page → App sidebar: composes · Home page includes sidebar shell
- Home page → Mailbox web: shows · Primary mailbox presentation on desktop/web
- Home page → Mailbox mobile: shows · Alternative mailbox presentation on mobile
- App sidebar → Sidebar web: selects · Web sidebar variant is chosen for desktop/web
- App sidebar → Sidebar mobile: selects · Mobile sidebar variant is chosen for handheld layout
- Mailbox web → Web item: renders · Desktop mailbox rows use a web item component
- Mailbox mobile → Mobile item: renders · Mobile mailbox rows use a mobile item component
- Mailbox web → useMails: reads state · Mailbox UI is driven by local mail state
- Mailbox mobile → useMails: reads state · Mailbox UI is driven by local mail state
- useMails → Mock mails: seeds · Local state starts from demo mail content
- useMails → Env config: checks · Feature flags decide whether mocks are active
- MSW worker → Mock handlers: registers · Browser worker installs request handlers
- Mock handlers → Mock mails: serves · Mock responses use fixture mail data
- Env config → MSW worker: enables · Environment controls whether the mock layer runs
- Capacitor → Desktop check: influences · Runtime/platform detection feeds presentation choice
- Android app → Capacitor: hosts · Android package embeds the Capacitor web app
- Vite → main.ts: builds · Vite bundles the frontend entry graph
- Cypress → Home page: tests · E2E coverage exercises the user-facing page
- Deploy flow → Vite: publishes · Deployment pipeline consumes the built web app
