Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (version >= 20.0.0)
npm (comes with Node.js)
Git
PostgreSQL (for local development)

Installation

1. Clone the Repository

git clone https://github.com/southwellmedia-dev/aether-platform.git
cd aether-platform

2. Install Dependencies

npm install

This will install all dependencies for the monorepo, including:

Web application dependencies
Plugin dependencies
Shared package dependencies

3. Set Up Environment Variables

Create a .env file in the root of the project:

cp .env.example .env

Update the following variables in your .env file:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/aether_dev"

# Better Auth
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"

# Optional: Debug flags
NEXT_PUBLIC_SHOW_RAW_ONBOARDING=true  # Show raw onboarding data in settings

4. Set Up the Database

Make sure PostgreSQL is running, then:

# Generate Prisma client
npm run db:generate

# Push schema to database
npm run db:push

# (Optional) Seed the database with test data
npm run db:seed

5. Start the Development Server

npm run dev

This starts:

Web app at http://localhost:3000
Documentation at http://localhost:4321/docs

Project Structure

aether-platform/
├── apps/
│   ├── web/              # Next.js web application
│   └── docs/             # Starlight documentation site
├── packages/
│   ├── core/             # Core domain & infrastructure
│   ├── database/         # Prisma schema and migrations
│   ├── ui/               # Shared UI components
│   ├── auth-utils/       # Authentication utilities
│   └── plugins/          # Plugin packages
│       ├── plugins-core/ # Plugin framework
│       ├── timer/        # Timer plugin
│       ├── tasks/        # Tasks plugin
│       └── ...
└── docs/
    ├── constitution/     # Architectural documentation
    └── guides/           # Developer guides

Development Workflow

Creating a New Plugin

npm run create:plugin

This interactive script will:

Prompt for plugin details (name, description)
Create plugin package structure
Generate manifest boilerplate
Update plugin registry

Generating Plugin Manifests

After making changes to plugin manifests:

npm run generate:manifests

This regenerates apps/web/src/lib/plugins/manifest-registry.generated.ts

Running Checks

# Type checking
npm run typecheck

# Linting
npm run lint

# Format code
npm run format

# Run tests
npm run test

Database Commands

# Generate Prisma client
npm run db:generate

# Push schema changes to database
npm run db:push

# Create a new migration
npm run db:migrate

# Open Prisma Studio (database GUI)
npm run db:studio

# Seed the database
npm run db:seed

Architecture Checks

Aether enforces constitutional architecture rules:

# Check domain purity (no infrastructure dependencies in domain layer)
npm run check:architecture

Troubleshooting

Port Already in Use

If port 3000 or 4321 is already in use:

# Kill all node processes (Windows)
taskkill /F /IM node.exe

# Kill all node processes (Mac/Linux)
killall node

Database Connection Issues

Ensure PostgreSQL is running
Verify DATABASE_URL in .env
Check database exists: psql -U postgres -l
Create database if missing: createdb aether_dev

Plugin Not Showing Up

Check plugin is enabled in Settings > Plugins
Verify business type matches plugin requirements
Regenerate manifests: npm run generate:manifests
Refresh the page

Build Errors

# Clean and rebuild
npm run clean:all
npm install
npm run generate:manifests
npm run build