core

Nexus Base

Nexus Base is a modern, modular, single-user application shell built for scalability and maintainability. It serves as the foundational “Operating System” for downstream applications (like TeamSeed and ArcNexus), providing a robust core with authentication, a dynamic registry-based UI shell, and a clean separation of concerns.

🚀 Key Features

• Registry/Shell Architecture: A dynamic “Operating System” UI pattern where features are loaded into zones (nav-main, header-end, details-panel) via a Registry, keeping the core shell immutable.
• Authentication: Secure, full-featured auth system using Auth.js (v5) with Prism Adapter. Includes registration, login, email verification, password reset, and role-based access control.
• Tech Stack:
  • Framework: Astro (Server-side rendering, API routes).
  • UI Library: React with Tailwind CSS.
  • Database: PostgreSQL with Prisma ORM.
  • State Management: Zustand (for Shell state).
  • Testing: Playwright (E2E).
• Production-Ready: Dockerized development and production environments.

🛠️ Prerequisites

Ensure you have the following installed:

• Node.js (v20+ recommended)
• Docker & Docker Compose
• npm

🏁 Getting Started

1. Clone & Install

git clone <repository-url>
cd app-core
npm install

2. Environment Setup

Copy the example environment file and configure it:

cp .env.example .env

Update .env with your secure secrets (Generate secrets with openssl rand -hex 32).

3. Start Development

To start the development server and the database automatically:

npm run dev

• URL: http://localhost:4321
• Database: PostgreSQL running on port 5432 (managed via compose.db.yml).

📦 Scripts & Commands

Command	Description
npm run dev	Starts Postgres (Docker) + Astro Dev Server.
npm run build	Builds the project for production.
npm run preview	Previews the production build locally.
npm run db:up	Starts only the PostgreSQL database container.
npm run db:down	Stops the PostgreSQL database container.
npm run docker:up	Starts the entire app (App + DB) in Docker mode.
npm run test:e2e	Runs End-to-End tests using Playwright in Docker.
npm run test:e2e:ui	Runs Playwright UI for interactive testing.

🧪 Testing

Nexus Base uses Playwright for rigorous End-to-End (E2E) testing.

To run tests in a headless CI-like environment (Dockerized):

npm run test:e2e

To run tests interactively with the Playwright UI:

npm run test:e2e:ui

🏗️ Architecture

Directory Structure

/
├── compose.db.yaml    # Postgres Service Definition
├── compose.yml        # Development Docker Compose (Extends db)
├── compose.test.yml   # Testing Docker Compose (Extends db)
├── Dockerfile         # Production Dockerfile
├── src/
│   ├── actions/       # Server Actions (Backend Logic)
│   │   └── core/      # Core User/Auth Actions
│   ├── components/    # Reusable UI Components
│   │   └── shell/     # Master Shell & Layouts
│   ├── lib/           # Utilities (DB, Email, Registry Loader)
│   ├── registry/      # UI Zones (The "Registry")
│   │   ├── nav-main/
│   │   ├── header-end/
│   │   └── ...
│   ├── layouts/       # Astro Layouts
│   └── pages/         # Astro Routes

The Shell Pattern

Everything is a “plugin”. The MasterShell loads components dynamically from src/registry/ into specific zones. To add a sidebar link, simply create a component in src/registry/nav-main/ with an exported order constant.

📝 License

Proprietary / Closed Source (Update as needed)