Architecture Overview

Overview

ARCA is built as a modern full-stack application using a monorepo architecture managed by Turborepo. The system consists of a NestJS backend API and a Next.js frontend application, both written in TypeScript.

Monorepo Structure

The project uses npm workspaces and Turborepo for efficient monorepo management:

arca/
├── apps/
│   ├── backend/              # NestJS API
│   └── frontend/             # Next.js web app
├── packages/                 # Shared packages (future)
├── turbo.json               # Turborepo configuration
└── package.json             # Root workspace config

Turborepo Configuration

The turbo.json defines pipeline tasks for building, linting, and development:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": { "dependsOn": ["^lint"] },
    "check-types": { "dependsOn": ["^check-types"] }
  }
}

The dev task runs with cache: false and persistent: true to ensure live-reload functionality during development.

Workspace Scripts

Root-level scripts orchestrate both applications:

# Development (runs both apps concurrently)
npm run dev

# Backend only (port 3333)
npm run -w backend start:dev

# Frontend only (port 3000)
npm run -w frontend dev

# Build both applications
npm run build

# Lint and format
npm run lint
npm run format

Backend Architecture

The backend is built with NestJS, a progressive Node.js framework that provides a robust architecture for building scalable server-side applications.

Technology Stack

NestJS

Framework for building efficient, scalable Node.js server-side applications

Prisma ORM

Next-generation ORM for type-safe database access

PostgreSQL

Robust relational database for data persistence

JWT Authentication

Secure token-based authentication with Passport.js

Directory Structure

apps/backend/
├── src/
│   ├── app.module.ts        # Root application module
│   ├── main.ts              # Application bootstrap
│   ├── auth/                # Authentication module
│   │   ├── auth.module.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── guards/          # JWT & Local auth guards
│   │   ├── hash/            # Password hashing module
│   │   └── dto/             # Data transfer objects
│   ├── users/               # User management module
│   │   ├── users.module.ts
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── dto/
│   ├── waitlist/            # Waitlist management module
│   │   ├── waitlist.module.ts
│   │   ├── waitlist.controller.ts
│   │   ├── waitlist.service.ts
│   │   ├── dto/
│   │   └── entities/
│   └── prisma/              # Prisma service module
│       ├── prisma.module.ts
│       └── prisma.service.ts
├── prisma/
│   ├── schema.prisma        # Database schema definition
│   ├── migrations/          # Database migrations
│   └── seed.ts              # Database seeding script
└── test/                    # E2E and unit tests

Module Architecture

NestJS follows a modular architecture pattern. The main modules are:

App Module

The root module that imports all feature modules:

@Module({
  imports: [
    ConfigModule.forRoot({        // Environment configuration
      isGlobal: true,
      envFilePath: process.env.NODE_ENV
        ? `.env.${process.env.NODE_ENV}`
        : '.env',
    }),
    AuthModule,                   // Authentication & authorization
    UsersModule,                  // User management
    WaitlistModule                // Waitlist management
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Authentication Flow

Local Strategy: Validates username/password credentials
JWT Strategy: Validates JWT tokens for protected routes
Guards: JwtAuthGuard protects routes requiring authentication
Password Hashing: Uses bcrypt for secure password storage

Prisma Integration

The PrismaService extends PrismaClient and is used as a global module:

Handles database connections
Provides type-safe database queries
Manages transactions and migrations

API Configuration

The main.ts file configures:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Global validation pipe
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
  }));

  // CORS configuration
  app.enableCors({
    origin: process.env.CORS_ORIGIN || 'http://localhost:3000',
    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
    credentials: true,
  });

  await app.listen(process.env.PORT ?? 3333);
}

The backend runs on port 3333 by default and accepts requests from the frontend on port 3000.

Frontend Architecture

The frontend is built with Next.js 15 using the App Router and React Server Components.

Technology Stack

Next.js 15

React framework with App Router and Server Components

React 19

Latest React with improved performance

TailwindCSS 4

Utility-first CSS framework for styling

NextAuth.js

Authentication for Next.js applications

Directory Structure

apps/frontend/
├── app/                     # Next.js App Router
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Homepage
│   ├── globals.css         # Global styles
│   ├── api/                # API routes (NextAuth)
│   ├── dashboard/          # Dashboard pages
│   ├── lista-espera/       # Waitlist pages
│   └── login/              # Login page
├── components/             # React components
│   ├── auth/               # Authentication components
│   ├── users/              # User management components
│   ├── waitlist/           # Waitlist components
│   └── ui/                 # Reusable UI components (shadcn/ui)
├── hooks/                  # Custom React hooks
├── lib/                    # Utility libraries
├── types/                  # TypeScript type definitions
├── utils/                  # Helper functions
└── middleware.ts           # Next.js middleware for auth

UI Component Library

ARCA uses shadcn/ui for component primitives:

Built on Radix UI primitives
Fully customizable with TailwindCSS
Includes: Avatar, Dialog, Dropdown, Select, Tooltip, and more
Form handling with React Hook Form and Zod validation

State Management

Server Components: For data fetching on the server
Client Components: For interactive UI with "use client"
React Hook Form: Form state management
Axios: HTTP client for API requests

Authentication Flow

NextAuth.js handles authentication on the frontend
Credentials provider connects to the backend /auth/login endpoint
JWT tokens stored in secure HTTP-only cookies
Middleware protects routes requiring authentication
Session data available via useSession() hook

Backend-Frontend Communication

API Integration

The frontend communicates with the backend via REST API:

Environment Configuration

Frontend uses NEXT_PUBLIC_API_URL or defaults to http://localhost:3333

HTTP Client

Axios instances configured with base URL and credentials

Authentication

NextAuth sends credentials to backend /auth/loginBackend validates and returns JWT token

Authorized Requests

JWT token included in Authorization header for protected routes

API Endpoints

Example endpoint structure:

Endpoint	Method	Description
`/auth/login`	POST	User authentication
`/users`	GET	List all users
`/users/:id`	GET	Get user by ID
`/waitlist`	GET	Get waitlist entries
`/waitlist`	POST	Create waitlist entry

CORS Configuration

The backend CORS is configured to accept requests from:

Development: http://localhost:3000
Production: Configured via CORS_ORIGIN environment variable

Development Workflow

Running the Application

# Install dependencies
npm install

# Start both apps concurrently
npm run dev

# Backend runs on http://localhost:3333
# Frontend runs on http://localhost:3000

Database Management

# Create migration
cd apps/backend
npx prisma migrate dev --name migration_name

# Apply migrations
npx prisma migrate deploy

Code Quality

# Lint all code
npm run lint

# Format with Prettier
npm run format

# Type checking
npm run check-types

Deployment Architecture

Frontend Deployment

Deploy to Vercel for automatic CI/CD and edge optimization

Backend Deployment

Deploy to Railway, Heroku, or containerize with Docker

Database

PostgreSQL on Supabase, Neon, or Railway

Environment Variables

Manage secrets per environment (dev, staging, production)

Environment Variables

Backend
Frontend

.env

DATABASE_URL="postgresql://user:password@host:5432/arca_db"
JWT_SECRET="your-secret-key"
CORS_ORIGIN="https://your-frontend.vercel.app"
PORT=3333

.env.local

NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret"
NEXT_PUBLIC_API_URL="http://localhost:3333"

Key Design Decisions

Why Monorepo?

Code Sharing: Easy to share types between frontend and backend
Atomic Commits: Changes across apps can be committed together
Simplified Dependency Management: One node_modules for shared deps
Consistent Tooling: Shared ESLint, Prettier, TypeScript configs

Why NestJS?

TypeScript-First: Strong typing and modern JavaScript features
Modular Architecture: Clean separation of concerns
Dependency Injection: Testable and maintainable code
Extensive Ecosystem: Built-in support for Swagger, GraphQL, WebSockets

Why Next.js App Router?

Server Components: Reduced client-side JavaScript
Streaming: Better performance with progressive rendering
Built-in Routing: File-system based routing
API Routes: Backend-for-frontend pattern support

Why Prisma?

Type Safety: Auto-generated types from schema
Developer Experience: Intuitive query API
Migration Management: Version-controlled schema changes
Prisma Studio: Visual database browser

Get Started

Core Features

User Management

Deployment

Development

​Overview

​Monorepo Structure

​Turborepo Configuration

​Workspace Scripts

​Backend Architecture

​Technology Stack

NestJS

Prisma ORM

PostgreSQL

JWT Authentication

​Directory Structure

​Module Architecture

​App Module

​Authentication Flow

​Prisma Integration

​API Configuration

​Frontend Architecture

​Technology Stack

Next.js 15

React 19

TailwindCSS 4

NextAuth.js

​Directory Structure

​UI Component Library

​State Management

​Authentication Flow

​Backend-Frontend Communication

​API Integration

​API Endpoints

​CORS Configuration

​Development Workflow

​Running the Application

​Database Management

​Code Quality

​Deployment Architecture

Frontend Deployment

Backend Deployment

Database

Environment Variables

​Environment Variables

​Key Design Decisions

Build docs developers (and LLMs) love

Overview

Monorepo Structure

Turborepo Configuration

Workspace Scripts

Backend Architecture

Technology Stack

Directory Structure

Module Architecture

App Module

Authentication Flow

Prisma Integration

API Configuration

Frontend Architecture

Technology Stack

Directory Structure

UI Component Library

State Management

Authentication Flow

Backend-Frontend Communication

API Integration

API Endpoints

CORS Configuration

Development Workflow

Running the Application

Database Management

Code Quality

Deployment Architecture

Environment Variables

Key Design Decisions