Nexus OS

Nexus OS is an AI-assisted adaptive operations suite with a React/Vite web frontend, a Node/Express backend, PostgreSQL persistence through Drizzle ORM, and an Expo mobile client. The current production topology is:

• Backend on Railway
• Frontend on Vercel
• Database on PostgreSQL

Core capabilities

• Adaptive workspace modes for rental, personal, professional, and custom operating models
• Cookie-authenticated web sessions with hardened environment validation
• AI-assisted module and action suggestions through the model gateway
• Fleet, bookings, customers, maintenance, tasks, notes, and analytics flows
• Web and mobile surfaces sharing the same domain model vocabulary

Stack

• Web frontend: React 19, Vite, TanStack Query, Wouter
• Backend: Express 5, TypeScript, esbuild bundle
• Database: PostgreSQL, Drizzle ORM, Drizzle Kit
• E2E: Playwright
• Security: npm audit, Trivy, Gitleaks, CodeQL
• Mobile: Expo / React Native

Quick start

1. Install dependencies:

npm ci
npm --prefix mobile ci

2. Configure local environment:

cp .env.example .env

3. Provide at minimum:

• DATABASE_URL
• SESSION_SECRET

4. Push the database schema:

npx drizzle-kit push

5. Start the local web/backend app:

npm run dev

The app runs on http://localhost:5000.

Validation

npm run lint
npm test
npm run test:integration
npm run build
npm run test:e2e
npm run security:audit
npm run security:scan

For the full repository validation pass, including the mobile workspace:

npm run validate

Operational recovery guides live in docs/runbooks/startup-and-db-recovery.md and docs/runbooks/ci-validation-recovery.md.

Deployment

Railway backend

Railway uses the checked-in railway.json and Dockerfile.

Required production variables:

• DATABASE_URL
• SESSION_SECRET
• CORS_ALLOWED_ORIGINS
• AI_PROVIDER
• OPENAI_API_KEY when AI_PROVIDER=openai

Deploy with:

railway up --service api --environment production

Health check:

curl https://<your-railway-domain>/health

Vercel frontend

Vercel uses the repo root with:

• build command: npm run build:web
• output directory: dist/public

Required environment variable:

• VITE_API_BASE_URL=https://<your-railway-domain>

Deploy with:

vercel deploy --prod

Security notes

• Runtime secrets must come from environment variables.
• Cookie-authenticated write endpoints require a CSRF token.
• Production web deployments must align VITE_API_BASE_URL and CORS_ALLOWED_ORIGINS.

Vision

The software should adapt to the operator rather than forcing the operator to adapt to the software. Nexus OS provides a unified shell, a flexible data model, and an AI layer that can assist without obscuring the underlying business state.

---

Author

Konstantinos Foskolakis Full-stack engineer — Heraklion, Crete, Greece github.com/kostasuser01gr

---

Portfolio Positioning

This project demonstrates full-stack product ownership across a multi-surface system: React/Vite web frontend, Express/TypeScript backend, PostgreSQL via Drizzle ORM, and an Expo mobile client sharing the same domain model. The architecture reflects real operational constraints — multi-mode workspaces, role-aware sessions, AI-assisted module suggestions, and a mobile client that mirrors the web data vocabulary. The security posture includes npm audit, Trivy, Gitleaks, and CodeQL in CI. The Playwright E2E suite validates the public portfolio overview route independently of auth state. This is production-style architecture applied to a portfolio-grade MVP.

Built as a portfolio-grade multi-platform operations suite. Estimated implementation effort for the current public version: 5–8 focused development days.