How hf1nacl/mailbox-demo works
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: HomePage.vue Home page · useMails.ts useMails · AppSidebar.vue App sidebar · MailboxWeb.vue Mailbox web
Components 25
Frontend app
Vue/Ionic web application shell and page flow
- index.html · Browser entry point
index.html - main.ts · Creates and mounts the Vue app
src/main.ts - App.vue · Top-level application component
src/App.vue - Main layout · Primary page shell and content frame
src/layouts/MainLayout.vue - Router · Routes into the visible page
src/router/index.ts - Home page · Single main page for the demo
src/views/HomePage.vue - App header · Top-level app chrome
src/components/app/AppHeader.vue - App sidebar · Sidebar composition boundary
src/components/app/AppSidebar.vue
Platform split
Web vs mobile adaptation boundaries
- Capacitor · Detects and adapts to native runtime
src/composables/capacitor.ts - Desktop check · Chooses desktop or mobile presentation
src/composables/isDesktop.ts - Sidebar web · Web sidebar implementation
src/components/app/sidebar/SidebarWeb.vue - Sidebar mobile · Mobile sidebar implementation
src/components/app/sidebar/SidebarMobile.vue
Mailbox UI
Mailbox presentation and local interaction state
- Mailbox web · Web mailbox list and interactions
src/components/mailbox/MailboxWeb.vue - Mailbox mobile · Mobile mailbox list and interactions
src/components/mailbox/MailboxMobile.vue - Web item · Desktop mailbox row component
src/components/mailbox/web/WebItem.vue - Mobile item · Mobile mailbox row component
src/components/mailbox/mobile/MobileItem.vue - useMails · Client-side mailbox state and actions
src/composables/useMails.ts
Mock data
Offline demo data and request interception
- Env config · Environment-driven feature toggles
src/config/env.ts - Mock mails · Offline demo mailbox content
src/mocks/mails.ts - MSW worker · Browser request interception setup
src/mocks/browser.ts - Mock handlers · Mock mail request handlers
src/mocks/handlers.ts
Android host
Capacitor-wrapped native Android shell
- Android app · Capacitor Android packaging and runtime
android/app/src/main/java/hf1nacl/mailboxdemo/vue/MainActivity.java
Tooling
Build, test, and deployment pipeline
- Vite · Frontend build and dev server
vite.config.ts - Cypress · End-to-end validation suite
cypress.config.ts - Deploy flow · Automated deployment workflow
.github/workflows/deploy.yml
Connections 25
- 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