archy-demo/neode-ui/README.md

Neode UI - Vue 3 Edition

A modern, clean Vue 3 + Vite + Tailwind rewrite of the Neode OS interface.

🎯 Why This Rewrite?

The original Angular interface had routing issues, disappearing components, and was difficult to maintain. This Vue 3 rewrite provides:

• ✅ Clean routing - Vue Router is simpler and more predictable than Angular router
• ✅ Modern tooling - Vite is 10x faster than Angular CLI
• ✅ Better DX - TypeScript + Vue 3 Composition API + Tailwind = rapid development
• ✅ Same glassmorphism design - All your beautiful UI styling recreated
• ✅ Same features - Splash screen, login, onboarding, apps list, etc.
• ✅ Backend agnostic - Connects to the same Rust backend via RPC/WebSocket

🏗️ Architecture

neode-ui/
├── src/
│   ├── api/              # RPC client & WebSocket handler
│   ├── stores/           # Pinia state management (replaces PatchDB)
│   ├── views/            # Page components
│   ├── components/       # Reusable components (SplashScreen, etc.)
│   ├── router/           # Vue Router configuration
│   ├── types/            # TypeScript types (ported from Angular)
│   └── style.css         # Global styles + Tailwind
├── public/assets/        # Static assets (images, fonts, icons)
└── vite.config.ts        # Vite config with proxy to backend

🚀 Getting Started

Prerequisites

• Node.js 20.19+ or 22.12+ (20.18.2 works but shows warning)

Quick Start (Recommended)

cd neode-ui
npm install
npm start

Visit http://localhost:8100 and login with password: password123

This starts both:

• ✅ Mock backend (port 5959) - no Docker required!
• ✅ Vite dev server (port 8100) with instant HMR

Stop servers:

npm stop

📖 See DEV-SCRIPTS.md for detailed documentation

Development Options

# Start everything (mock backend + Vite)
npm start

# Stop everything
npm stop

# Run mock backend only
npm run backend:mock

# Run Vite only (requires backend running separately)
npm run dev

# Run with real Rust backend (requires core/ to be running)
npm run dev:real

Build for Production

npm run build

Outputs to ../web/dist/neode-ui/

🎨 Design System

Glassmorphism Classes

<!-- Glass card -->
<div class="glass-card p-6">Content</div>

<!-- Glass button -->
<button class="glass-button px-4 py-3">Click me</button>

<!-- Manual glass styling -->
<div class="bg-glass-dark backdrop-blur-glass border border-glass-border shadow-glass">
  Custom glass element
</div>

Spacing (4px grid system)

• p-4 = 16px padding
• m-6 = 24px margin
• gap-4 = 16px gap

Colors

• text-white/80 = 80% white opacity
• bg-glass-dark = rgba(0, 0, 0, 0.35)
• border-glass-border = rgba(255, 255, 255, 0.18)

🔌 API Connection

RPC Calls

import { rpcClient } from '@/api/rpc-client'

// Login
await rpcClient.login('password')

// Start a package
await rpcClient.startPackage('bitcoin')

// Get metrics
const metrics = await rpcClient.getMetrics()

State Management (Pinia)

import { useAppStore } from '@/stores/app'

const store = useAppStore()

// Access reactive state
const packages = computed(() => store.packages)
const isAuthenticated = computed(() => store.isAuthenticated)

// Call actions
await store.login(password)
await store.installPackage('nextcloud', marketplaceUrl, '1.0.0')

WebSocket Updates

The store automatically subscribes to WebSocket updates and applies JSON patches to the state. No manual setup required!

📝 Routes

Route	Component	Description
/	Redirect	Redirects to /login
/login	Login	Login page with glass styling
/onboarding/intro	OnboardingIntro	Welcome screen
/onboarding/options	OnboardingOptions	Setup options
/dashboard	Dashboard	Main layout with sidebar
/dashboard/apps	Apps	Apps list with glass cards
/dashboard/apps/:id	AppDetails	App details page
/dashboard/marketplace	Marketplace	Browse apps
/dashboard/server	Server	Server settings
/dashboard/settings	Settings	UI settings

✨ Features Recreated

• Alien-style terminal splash screen with typing animation
• Skip intro button
• Login page with glass card and fade-up animation
• Onboarding intro with feature highlights
• Onboarding options with selectable glass cards
• Dashboard layout with glass sidebar
• Apps list with status badges and quick actions
• Connection status banner
• Offline detection
• WebSocket state synchronization
• RPC authentication
• Responsive design

🐛 Debugging

Common Issues

Assets not loading?

# Ensure assets are copied
cp -r ../web/projects/shared/assets/img/* public/assets/img/

Backend connection refused?

• Check backend is running on port 5959
• Update proxy in vite.config.ts if using different port

TypeScript errors?

npm run type-check

📦 Deployment

The Vue app can be served by the Rust backend (replace the Angular build):

1. Build: npm run build (outputs to ../web/dist/neode-ui/)
2. Update Rust to serve from this directory
3. Restart backend

🔮 Future Enhancements

• Dark/light theme toggle
• App configuration UI
• Marketplace browsing & search
• Server metrics charts
• Backup/restore UI
• Notification system
• Multi-language support

🤝 Contributing

This is a clean rewrite - feel free to add features without the baggage of the old Angular codebase!

📄 License

Same as Neode OS