Quick Start

Overview

This guide will walk you through starting ARCA and accessing the application for the first time. If you haven’t installed ARCA yet, please follow the Installation Guide first.

Make sure you’ve completed all installation steps, including database setup and migrations, before proceeding.

Starting the Development Servers

Start Both Applications

From the project root directory, start both the backend and frontend simultaneously:

npm run dev

This command uses concurrently to run both servers in parallel:

Backend runs on port 3333 (magenta output)
Frontend runs on port 3000 (cyan output)

You should see output similar to:

[backend] [Nest] 12345  - 03/03/2026, 10:00:00 AM     LOG [NestFactory] Starting Nest application...
[backend] [Nest] 12345  - 03/03/2026, 10:00:00 AM     LOG [InstanceLoader] AppModule dependencies initialized
[backend] [Nest] 12345  - 03/03/2026, 10:00:00 AM     LOG [NestApplication] Nest application successfully started
[backend] [Nest] 12345  - 03/03/2026, 10:00:00 AM     LOG Application listening on port 3333

[frontend]   ▲ Next.js 15.5.1
[frontend]   - Local:        http://localhost:3000
[frontend]   - Turbopack:    enabled
[frontend]
[frontend]  ✓ Ready in 2.5s

The first start may take longer as Next.js compiles pages and Turbopack optimizes the build.

Access the Frontend

Open your browser and navigate to:

http://localhost:3000

You should see the ARCA login page.

If you see a connection error, ensure the backend is running on port 3333 and the DATABASE_URL is correctly configured.

Verify Backend API

The backend API is available at:

http://localhost:3333

You can test the API health by visiting http://localhost:3333/health or any defined endpoint.

Alternative: Start Applications Separately

You can also run the backend and frontend in separate terminal windows for better log visibility:

npm run dev:backend
# Starts NestJS on port 3333

Running servers separately is useful when debugging specific issues or when you only need to work on one part of the application.

Access the Login Page

Navigate to http://localhost:3000 in your browser.

Use Default Credentials

If you’ve run the database seed (automatically executed during prisma migrate dev), you should have default users created.Check your backend seed file for default credentials, or create a new user through the registration flow if available.

Default credentials should only be used in development. Always change passwords in production environments.

Explore the Dashboard

After logging in, you’ll have access to:

Patient Management - View and create patient records
Waitlist - Manage candidates awaiting treatment
Appointments - Schedule and track consultations
Documents - Upload and manage clinical documents
Reports - Generate discharge and progress reports
Audit Logs - View system activity (supervisor role)

Database Management

ARCA includes Prisma Studio for visual database management:

cd apps/backend
npx prisma studio

Prisma Studio opens at http://localhost:5555 and allows you to:

View Data

Browse all tables and records in your database

Edit Records

Modify data directly through the web interface

Create Entries

Add new users, patients, or appointments

Inspect Schema

Explore relationships and constraints

Available Scripts

ARCA provides several npm scripts for different tasks:

Development

npm run dev
# Runs backend (port 3333) and frontend (port 3000) in parallel

Build

npm run build
# Creates production builds of both applications using Turborepo

This command:

Builds the NestJS backend to apps/backend/dist/
Builds the Next.js frontend to apps/frontend/.next/
Uses Turborepo caching for faster subsequent builds

Code Quality

npm run lint
# Runs ESLint on all workspace packages

Database Operations

cd apps/backend
npx prisma migrate dev
# Creates and applies a new migration

Understanding the Monorepo

ARCA uses Turborepo to manage the monorepo efficiently:

Workspace Structure

arca/
├── apps/
│   ├── backend/    # NestJS API application
│   └── frontend/   # Next.js web application
└── packages/       # Shared packages (future)

Turborepo Benefits

Caching

Builds are cached and reused across runs

Parallelization

Tasks run in parallel when possible

Dependency Graph

Automatic task ordering based on dependencies

Remote Caching

Share cache across team members (configurable)

Turborepo Tasks

The turbo.json configuration defines these tasks:

build - Production builds with caching
lint - Code linting across workspaces
check-types - TypeScript validation
dev - Development mode (cache disabled for live reloading)

API Testing

You can test the backend API using tools like cURL, Postman, or HTTPie:

curl http://localhost:3333/health

Most endpoints require JWT authentication. Include the token in the Authorization header: Bearer <token>

Hot Reload

Both applications support hot reload during development:

Backend: NestJS watches for file changes and automatically restarts
Frontend: Next.js with Turbopack provides instant HMR (Hot Module Replacement)

Simply save your files and see changes reflected immediately.

Stopping the Servers

To stop the development servers:

Press Ctrl+C in the terminal running npm run dev
Wait for both processes to terminate gracefully

If processes don’t stop:

# Kill processes on specific ports (macOS/Linux)
lsof -ti:3000 | xargs kill -9  # Frontend
lsof -ti:3333 | xargs kill -9  # Backend

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Next Steps

Now that ARCA is running, you can:

API Reference

Explore the complete REST API documentation

Configuration

Configure authentication, database, and deployment

Patient Management

Learn how to manage patient records

Deployment

Deploy ARCA to production

Troubleshooting

Port already in use

If you see “Port 3000 (or 3333) is already in use”:

# Find the process using the port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill the process or change ARCA's port
# Backend: Set PORT in apps/backend/.env
# Frontend: Run with custom port
npm run dev:frontend -- -p 3001

Database connection failed

Verify PostgreSQL is running and DATABASE_URL is correct:

# Check PostgreSQL status
psql -U postgres -c "SELECT version();"

# Test connection with your DATABASE_URL
psql "postgresql://username:password@localhost:5432/arca_db"

Ensure the database exists and credentials match apps/backend/.env.

Module not found errors

Reinstall dependencies and regenerate Prisma Client:

# Clean install
rm -rf node_modules apps/*/node_modules
npm install

# Regenerate Prisma
cd apps/backend
npx prisma generate

Frontend shows API errors

Ensure:

Backend is running on port 3333
Frontend API URL is correctly configured
CORS is properly configured in the backend
JWT_SECRET matches between backend .env and frontend config

For additional help, check the project README or open an issue on GitHub.

Get Started

Core Features

User Management

Deployment

Development

Quick Start

Overview

Starting the Development Servers

Alternative: Start Applications Separately

Database Management

View Data

Edit Records

Create Entries

Inspect Schema

Available Scripts

Development

Build

Code Quality

Database Operations

Understanding the Monorepo

Workspace Structure

Turborepo Benefits

Caching

Parallelization

Dependency Graph

Remote Caching

Turborepo Tasks

API Testing

Hot Reload

Stopping the Servers

Next Steps

API Reference

Configuration

Patient Management

Deployment

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

User Management

Deployment

Development

​Overview

​Starting the Development Servers

​Alternative: Start Applications Separately

​First Login

​Database Management

View Data

Edit Records

Create Entries

Inspect Schema

​Available Scripts

​Development

​Build

​Code Quality

​Database Operations

​Understanding the Monorepo

​Workspace Structure

​Turborepo Benefits

Caching

Parallelization

Dependency Graph

Remote Caching

​Turborepo Tasks

​API Testing

​Hot Reload

​Stopping the Servers

​Next Steps

API Reference

Configuration

Patient Management

Deployment

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Starting the Development Servers

Alternative: Start Applications Separately

First Login

Database Management

Available Scripts

Development

Build

Code Quality

Database Operations

Understanding the Monorepo

Workspace Structure

Turborepo Benefits

Turborepo Tasks

API Testing

Hot Reload

Stopping the Servers

Next Steps

Troubleshooting