Skip to main content

​
Overview

ARCA is a full-stack monorepo application built with NestJS (backend) and Next.js (frontend), managed by Turborepo. This guide will walk you through the initial setup process.

​
Prerequisites

Before starting, ensure you have the following installed:

Node.js

Version 18 or higher required

PostgreSQL

Any recent version (12+)

npm

Version 10 or higher

Git

For version control

​
Installation

1

Clone the Repository

Clone the ARCA repository to your local machine:
git clone https://github.com/pedrokourly/arca.git
cd arca
2

Install Dependencies

Install all dependencies for the monorepo using npm workspaces:
npm install
This command will install dependencies for:
  • Root workspace
  • Backend application (apps/backend)
  • Frontend application (apps/frontend)
  • Shared packages
3

Set Up Environment Variables

Create environment files for both applications. Start with the backend:
cp apps/backend/.env.example apps/backend/.env
Then edit apps/backend/.env with your configuration. See the Configuration page for details.
4

Configure Database Connection

In your apps/backend/.env file, set the DATABASE_URL:
DATABASE_URL="postgresql://usuario:senha@localhost:5432/arca_db"
Replace usuario, senha, and arca_db with your PostgreSQL credentials and database name.
5

Run Database Migrations

Navigate to the backend directory and run Prisma migrations:
cd apps/backend
npx prisma migrate dev
This will create all required tables in your database.
6

Seed the Database

Populate the database with initial data (roles, users, lookup tables):
npm run db:seed
This creates default users for each role:
Change these default passwords in production!
7

Return to Project Root

Navigate back to the project root:
cd ../..
8

Start Development Servers

Start both backend and frontend in development mode:
npm run dev
This runs both applications concurrently:

​
Verify Installation

After starting the development servers:
The backend API should be running on port 3333. You can verify it’s working by checking the health endpoint (if implemented) or attempting to access the API.
curl http://localhost:3333
Open your browser and navigate to:
http://localhost:3000
You should see the ARCA login page.
For database visualization and management:
cd apps/backend
npx prisma studio
This opens a web interface at http://localhost:5555

​
Available Scripts

The monorepo includes several useful scripts: 
# Start both applications
npm run dev

# Start backend only (port 3333)
npm run dev:backend

# Start frontend only (port 3000)
npm run dev:frontend

​
Project Structure

Understand the monorepo organization: 
arca/
├── apps/
│   ├── backend/              # NestJS API
│   │   ├── src/
│   │   │   ├── app/         # Application modules
│   │   │   ├── prisma/      # Prisma configuration
│   │   │   └── main.ts      # Application bootstrap
│   │   ├── prisma/
│   │   │   ├── schema.prisma # Database schema
│   │   │   ├── migrations/   # Database migrations
│   │   │   └── seed.ts      # Database seed script
│   │   └── package.json
│   └── frontend/             # Next.js interface
│       ├── src/
│       │   ├── app/         # Next.js App Router
│       │   ├── components/  # React components
│       │   ├── contexts/    # React contexts
│       │   ├── hooks/       # Custom hooks
│       │   └── lib/         # Utilities
│       └── package.json
├── packages/                 # Shared packages (future)
├── turbo.json               # Turborepo configuration
└── package.json             # Root configuration

​
Troubleshooting

If port 3333 or 3000 is already in use:
# For backend, set PORT environment variable
PORT=3334 npm run dev:backend

# For frontend, Next.js will automatically suggest an alternative port
Ensure:
  • PostgreSQL is running
  • Database exists (create it if needed: createdb arca_db)
  • Credentials in .env are correct
  • Database URL format is correct
If you encounter Prisma Client errors:
cd apps/backend
npx prisma generate
Clear build cache and rebuild:
# Remove node_modules and reinstall
rm -rf node_modules apps/*/node_modules
npm install

# Clear Turborepo cache
npx turbo clean

# Rebuild
npm run build

​
Next Steps

Configuration

Configure environment variables for your deployment

Database Setup

Learn more about database migrations and management

Production Deployment

Deploy ARCA to production environments

Architecture

Understand the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us