Technology Stack¶

Complete reference of technologies used in Mavric DevEnv projects.

Backend Stack¶

Apso Framework¶

The core backend framework that generates production-ready NestJS applications.

Component	Technology	Purpose
Runtime	Node.js 20+	JavaScript runtime
Framework	NestJS	Enterprise Node.js framework
Language	TypeScript	Type-safe JavaScript
Database	PostgreSQL	Relational database
ORM	TypeORM	Database abstraction
Validation	class-validator	DTO validation
API Style	REST	HTTP API endpoints

Key Dependencies¶

{
  "dependencies": {
    "@nestjs/common": "^10.0.0",
    "@nestjs/core": "^10.0.0",
    "@nestjs/typeorm": "^10.0.0",
    "typeorm": "^0.3.0",
    "pg": "^8.0.0",
    "class-validator": "^0.14.0",
    "class-transformer": "^0.5.0",
    "better-auth": "^1.0.0"
  }
}

Generated Code Structure¶

backend/
├── src/
│   ├── autogen/           # Generated by Apso
│   │   ├── Entity/
│   │   │   ├── Entity.entity.ts
│   │   │   ├── Entity.service.ts
│   │   │   ├── Entity.controller.ts
│   │   │   └── Entity.module.ts
│   │   └── guards/
│   └── extensions/        # Your custom code
├── .apsorc               # Schema definition
└── package.json

Frontend Stack¶

Next.js Application¶

Component	Technology	Purpose
Framework	Next.js 14+	React framework
Language	TypeScript	Type-safe JavaScript
Styling	Tailwind CSS	Utility-first CSS
Components	shadcn/ui	Component library
State	React Query	Server state management
Forms	React Hook Form	Form handling
Validation	Zod	Schema validation

Key Dependencies¶

{
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "tailwindcss": "^3.4.0",
    "@tanstack/react-query": "^5.0.0",
    "react-hook-form": "^7.0.0",
    "zod": "^3.0.0",
    "@hookform/resolvers": "^3.0.0"
  }
}

Frontend Structure¶

frontend/
├── app/                  # Next.js App Router
│   ├── (auth)/          # Auth routes
│   ├── (dashboard)/     # Protected routes
│   └── api/             # API routes
├── components/
│   ├── ui/              # shadcn/ui components
│   ├── forms/           # Form components
│   └── features/        # Feature components
├── lib/
│   ├── api.ts           # API client
│   └── auth.ts          # Auth config
└── hooks/               # Custom hooks

Authentication¶

BetterAuth¶

Modern authentication library integrated with Apso backends.

Feature	Implementation
Sessions	Database-stored sessions
Providers	Email/password, OAuth
Security	bcrypt hashing, secure cookies
Multi-tenant	Organization-scoped

Auth Entities¶

BetterAuth requires these database entities:

User - User accounts
Session - Active sessions
Account - OAuth provider links
Verification - Email verification tokens

Configuration¶

// Backend: auth configuration
import { betterAuth } from 'better-auth';

export const auth = betterAuth({
  database: {
    type: 'postgres',
    url: process.env.DATABASE_URL,
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 days
    updateAge: 60 * 60 * 24,     // 1 day
  },
});

Database¶

PostgreSQL¶

Aspect	Configuration
Version	14+ recommended
Default Port	5432
Connection	Via DATABASE_URL
Pooling	TypeORM connection pool

Docker Setup¶

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

Connection String Format¶

postgresql://user:password@host:port/database

Example:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp

Testing Stack¶

BDD Testing¶

Tool	Purpose
Cucumber	BDD test runner
Gherkin	Scenario syntax
Chai	Assertions
Jest	Unit testing

Test Structure¶

features/
├── api/                 # API tests (40%)
├── ui/                  # UI tests (45%)
├── e2e/                 # E2E tests (15%)
└── step-definitions/    # Step implementations

Test Commands¶

# Run all tests
npm test

# Run by layer
npm test -- --tags "@api"
npm test -- --tags "@ui"
npm test -- --tags "@e2e"

# Run by priority
npm test -- --tags "@smoke"
npm test -- --tags "@critical"

Development Tools¶

Required Tools¶

Tool	Version	Purpose
Node.js	20+	JavaScript runtime
npm	10+	Package manager
Docker	Latest	Container runtime
Git	2.0+	Version control
Claude Code	Latest	AI assistant

Optional Tools¶

Tool	Purpose
pgAdmin	PostgreSQL GUI
Postman	API testing
VS Code	Code editor

Environment Variables¶

Backend (.env)¶

# Server
NODE_ENV=development
PORT=3001

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp

# Authentication
AUTH_SECRET=your-secret-key-min-32-chars
BETTER_AUTH_URL=http://localhost:3001

# CORS
CORS_ORIGIN=http://localhost:3000

Frontend (.env.local)¶

# API
NEXT_PUBLIC_API_URL=http://localhost:3001

# Auth
NEXT_PUBLIC_AUTH_URL=http://localhost:3001

Version Compatibility¶

Tested Combinations¶

Node.js	Next.js	NestJS	PostgreSQL
20.x	14.x	10.x	16.x
22.x	14.x	10.x	16.x

Minimum Requirements¶

Node.js 20.0.0+
PostgreSQL 14.0+
npm 10.0+
Docker 20.0+ (for local development)

Package Scripts¶

Backend¶

{
  "scripts": {
    "start:dev": "nest start --watch",
    "build": "nest build",
    "start:prod": "node dist/main",
    "test": "jest",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}

Frontend¶

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "test": "jest"
  }
}