AspidIOT Desktop App

AspidIOT is an Electron desktop app with a React renderer.

Current implementation includes:

• Branded splash screen
• Unlock transition (lock animation + flash + sound)
• Login screen UI
• Renderer-side flow logic ready to connect to real auth/backend tunnel logic

Tech Stack

• Runtime: Electron ^35.7.5
• Renderer: React ^19 + Vite ^7
• Styling: css/styles.css (existing app styles preserved)
• Package manager: npm
• Main process entry: main.js

Project Structure

AspidIOT-App-R/
  assets/
    logo.png
    lock.svg
    open_lock.svg
    lock_sound.wav
  css/
    styles.css
  scripts/
    start-electron.js
  src/
    App.jsx
    main.jsx
  index.html
  main.js
  preload.js
  vite.config.js
  package.json
  package-lock.json
  .gitignore
  instructions.txt
  README.md

How It Works

1) Main Process (main.js)

• Creates the Electron BrowserWindow
• Loads renderer from:
  • VITE_DEV_SERVER_URL in dev
  • dist/index.html in production
• Sets secure renderer defaults:
  • contextIsolation: true
  • nodeIntegration: false
• Handles lifecycle events:
  • app.whenReady()
  • macOS-style activate
  • quit on window-all-closed (except macOS)

2) Preload (preload.js)

• Placeholder file for future IPC wiring
• Intended for exposing safe APIs from main/background logic to renderer

3) Renderer (src/App.jsx, src/main.jsx, css/styles.css)

• React renders three UI states:
  • Splash screen
  • Unlock screen
  • Login screen
• CSS classes/timings match previous behavior
• Lock sound plays during unlock transition

UI Flow

1. App opens on splash screen.
2. User clicks Click to start (or splash backdrop).
3. Unlock screen appears:
   • Flash and ripple effects trigger
   • Lock sound plays
   • Lock icon transitions from closed to open
4. App transitions to login screen.
5. Login submit is currently placeholder behavior.

Current unlock timings (src/App.jsx)

• Flash/ripple starts: ~520ms after click
• Lock icon swaps: ~220ms after flash/ripple starts
• Move to login: ~2000ms after click

NPM Scripts

Defined in package.json:

• npm start
  • Starts Vite dev server + Electron together
• npm run build
  • Builds renderer to dist/
• npm run start:prod
  • Builds renderer and starts Electron loading built files

Setup and Run

Prerequisites

• Node.js (LTS recommended)
• npm

Install dependencies

npm install

Dev run

npm start

Production-style local run

npm run start:prod

Security Posture (Current)

• contextIsolation is enabled
• nodeIntegration is disabled
• No renderer access to Node APIs by default

This is a good base for safely adding IPC in preload.js.

Where To Add IoT Logic

Your tunnel/device backend can be integrated in one of these patterns:

• Main process service:

  • Run device/tunnel managers in main.js or imported modules
  • Expose controlled methods/events via preload + IPC

• Background worker process:

  • Spawn a separate Node process for tunnel/device operations
  • Forward status/events to renderer through main process

Recommended for maintainability:

• Keep renderer UI-only
• Keep device/tunnel logic out of renderer
• Use preload.js as the strict bridge

Current Functional Scope

Implemented:

• UI shell and transitions
• Static login form
• Branded assets and visual behavior

Not implemented yet:

• Real authentication
• Dashboard page
• Device discovery/connection
• Tunnel management
• Data decrypt/forward pipeline
• Logs/telemetry persistence

Suggested Next Steps

1. Add a React dashboard screen/component
2. Wire login success to navigate/transition into dashboard
3. Define IPC contract in preload (window.api.*)
4. Implement background IoT/tunnel service module
5. Add structured logging and error reporting

Git Notes

• node_modules/ is excluded via .gitignore
• dist/ is excluded via .gitignore
• Lock and media assets are tracked under assets/