Skip to main content

​
Prerequisites

Before installing ARCA, ensure you have the following tools installed on your system:

Node.js

Version 18 or higher required

PostgreSQL

Latest stable version recommended

npm

Version 10 or higher (comes with Node.js)

Git

For cloning the repository
ARCA uses npm workspaces and Turborepo for monorepo management. The package manager is locked to [email protected] for consistency.

​
Verify Prerequisites

Check that you have the required versions installed: 
node --version
# Should output v18.x.x or higher

​
Installation Steps

1

Clone the Repository

Clone the ARCA repository from GitHub to your local machine:
git clone https://github.com/pedrokourly/arca.git
cd arca
This creates a local copy of the ARCA monorepo with all apps and configurations.
2

Install Dependencies

Install all dependencies for the monorepo using npm:
npm install
This command:
  • Installs root dependencies (Turborepo, Prettier, etc.)
  • Installs backend dependencies (NestJS, Prisma, bcrypt)
  • Installs frontend dependencies (Next.js, React, TailwindCSS)
  • Links workspace packages together
The installation uses npm workspaces to manage dependencies across the monorepo. This may take a few minutes on first install.
3

Configure PostgreSQL Database

Create a PostgreSQL database for ARCA:
# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE arca_db;

# Exit psql
\q
Make note of your PostgreSQL username, password, and database name. You’ll need these for the connection string.
4

Set Up Environment Variables

Create a .env file in the backend directory:
cp apps/backend/.env.example apps/backend/.env
Edit apps/backend/.env and configure your database connection:
apps/backend/.env
DATABASE_URL="postgresql://username:password@localhost:5432/arca_db"
JWT_SECRET="your-super-secret-jwt-key-change-this-in-production"
PORT=3333
Replace username and password with your PostgreSQL credentials. Generate a secure random string for JWT_SECRET in production.
5

Run Database Migrations

Navigate to the backend directory and execute Prisma migrations:
cd apps/backend
npx prisma migrate dev
This command:
  • Creates all required database tables
  • Sets up relationships and constraints
  • Generates the Prisma Client
  • Seeds initial data (roles, etc.)
You should see output indicating successful migration:
Applying migration `20240101000000_init`
The following migration(s) have been applied:

migrations/
  └─ 20240101000000_init/
    └─ migration.sql

Your database is now in sync with your schema.
6

Return to Project Root

Navigate back to the project root directory:
cd ../..
You’re now ready to start the development servers.

​
Verify Installation

You can verify that everything is set up correctly by checking the Prisma schema: 
cd apps/backend
npx prisma studio
This opens Prisma Studio in your browser at http://localhost:5555, where you can:
  • View all database tables
  • Inspect the schema structure
  • Verify migrations were applied
  • See initial seed data
Press Ctrl+C in the terminal to stop Prisma Studio when you’re done exploring.

​
Project Structure

After installation, your project structure should look like this: 
arca/
├── apps/
│   ├── backend/              # NestJS API
│   │   ├── src/
│   │   │   ├── app/         # Application modules
│   │   │   ├── prisma/      # Prisma configuration
│   │   │   └── main.ts      # Application bootstrap
│   │   ├── prisma/
│   │   │   ├── schema.prisma # Database schema
│   │   │   └── migrations/   # Database migrations
│   │   ├── .env             # Environment variables (you created this)
│   │   └── package.json
│   └── frontend/             # Next.js app
│       ├── src/
│       │   ├── app/         # Next.js App Router
│       │   ├── components/  # React components
│       │   ├── contexts/    # React contexts
│       │   ├── hooks/       # Custom React hooks
│       │   └── lib/         # Utilities
│       └── package.json
├── node_modules/            # Installed dependencies
├── turbo.json              # Turborepo configuration
└── package.json            # Root configuration

​
Database Schema

The ARCA database includes the following main entities:

Usuarios

Users (interns and supervisors) with role-based access

Pacientes

Patient records with demographics and medical history

Atendimentos

Appointment sessions with timestamps and observations

Documentos

Clinical documents with version control

RelatorioAlta

Discharge reports and clinical assessments

LogAuditoria

Audit logs for compliance and traceability

​
Troubleshooting

Make sure PostgreSQL is running:
# macOS (Homebrew)
brew services start postgresql

# Linux (systemd)
sudo systemctl start postgresql

# Windows
# Start PostgreSQL from Services or pg_ctl
Verify the DATABASE_URL in apps/backend/.env matches your PostgreSQL configuration.
Generate the Prisma Client manually:
cd apps/backend
npx prisma generate
This creates the type-safe database client used by the backend.
If port 3000 or 3333 is already in use, you can change them:
  • Backend: Set PORT=3334 in apps/backend/.env
  • Frontend: Use npm run dev:frontend -- -p 3001 or set in package.json
Clear npm cache and try again:
npm cache clean --force
rm -rf node_modules
rm package-lock.json
npm install
Ensure you’re using Node.js 18 or higher and npm 10 or higher.

​
Next Steps

Now that ARCA is installed, proceed to the Quick Start Guide to start the development servers and explore the application.

Quick Start

Learn how to start ARCA and access the application

Build docs developers (and LLMs) love

Get started for freeTalk to us