New Developer Onboarding

Welcome to Noumaris! This guide will help you get set up and productive quickly.

Prerequisites

Before you begin, ensure you have:

• macOS or Linux (Windows via WSL2)
• Node.js 18+ and npm
• Python 3.11+
• Poetry (Python dependency manager)
• Docker and Docker Compose
• Git
• A code editor (VS Code recommended)

Step 1: Clone the Repository

git clone https://github.com/nirojan95/noumaris.git
cd noumaris
git checkout develop

Step 2: Start Infrastructure Services

# Start PostgreSQL and Keycloak
docker-compose up -d

# Verify services are running
docker-compose ps

# Expected output:
# postgres   - Port 5433
# keycloak   - Port 8081

Wait ~30 seconds for Keycloak to fully start.

Step 3: Configure Keycloak with Terraform

# Run the automated setup script
bash scripts/setup-local-keycloak.sh

# This script will:
# 1. Wait for Keycloak to be ready
# 2. Initialize Terraform
# 3. Create realm, roles, and clients
# 4. Configure service accounts

Verify Keycloak:

• Visit http://localhost:8081
• Login: admin / admin
• Check that noumaris realm exists

Step 4: Set Up Backend

cd backend

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

# Apply database migrations
alembic upgrade head

# Seed database with templates and tags
python seed_db.py

# Seed feature permissions
python scripts/seed_features.py

# Run development server
python -m uvicorn src.noumaris_backend.api.main:app --reload

Verify Backend:

• Visit http://localhost:8000/docs (Swagger UI)
• You should see API documentation

Step 5: Set Up Frontend

Open a new terminal:

cd frontend

# Install dependencies
npm install

# Run development server (localhost mode)
npm run localhost

# This uses .env.localhost configuration

Verify Frontend:

• Visit http://localhost:5173
• You should see the Noumaris login page

Step 6: Test Login

Use one of the pre-configured test accounts created by seed_db.py (password google123 for all):

• Superadmin: [email protected]
• Institution Admin: [email protected]
• Resident: [email protected]
• Physician (read-only): [email protected]

Step 7: Explore the Application

As Superadmin

1. Login with [email protected]
2. Navigate to /admin/superadmin
3. View institutions, create new ones, grant features

As Institution Admin

1. Login with [email protected]
2. Navigate to /admin/institution
3. View residents, invite new ones, manage permissions

As Resident

1. Login with [email protected]
2. Navigate to the resident dashboard
3. Try creating a clinical note or reviewing templates

Project Structure

noumaris/
├── backend/                # FastAPI backend
│   ├── src/               # Source code
│   ├── tests/             # Tests
│   ├── alembic/           # Database migrations
│   └── scripts/           # Utility scripts
├── frontend/              # React frontend
│   ├── src/               # Source code
│   └── public/            # Static assets
├── landing/               # Marketing site (Astro)
├── terraform/             # Infrastructure as Code
│   └── keycloak/          # Keycloak configuration
├── docs/                  # This documentation (VitePress)
└── docker-compose.yml     # Local dev services

Development Workflow

Making Changes

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes:

   • Backend: Edit files in backend/src/
   • Frontend: Edit files in frontend/src/

3. Test your changes:

   # Backend tests
   cd backend && pytest tests/
   
   # Frontend (manual testing for now)
   cd frontend && npm run dev

4. Commit your changes:

   git add .
   git commit -m "feat: Add your feature description"

5. Push and create PR:

   git push origin feature/your-feature-name
   # Then create PR on GitHub

Database Migrations

When you change database models:

cd backend

# Generate migration
alembic revision --autogenerate -m "description of change"

# Review migration file in alembic/versions/

# Apply migration
alembic upgrade head

# If needed, rollback
alembic downgrade -1

Running Tests

# Backend unit tests
cd backend
pytest tests/ -v

# Backend API tests
pytest tests/test_admin_apis.py -v

# Frontend tests (when available)
cd frontend
npm run test

Common Issues

Port Already in Use

If you see "port already in use" errors:

# Check what's using the port
lsof -i :8000  # Backend
lsof -i :5173  # Frontend
lsof -i :5433  # PostgreSQL
lsof -i :8081  # Keycloak

# Kill the process
kill -9 <PID>

Docker Services Won't Start

# Stop all services
docker-compose down

# Remove volumes (WARNING: deletes data)
docker-compose down -v

# Restart
docker-compose up -d

Keycloak Connection Issues

# Verify Keycloak is running
curl http://localhost:8081/health

# Check logs
docker-compose logs keycloak

# Restart Keycloak
docker-compose restart keycloak

Database Connection Issues

# Verify PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres psql -U medical_user -d medical_db

Next Steps

1. Read the Architecture: Architecture Overview
2. Understand Decisions: Why we chose our tech stack
3. Explore the API: API Documentation
4. Learn Development Workflow: Development Guide

Getting Help

• Documentation: You're reading it! Start here.
• Code Questions: Ask in team Slack or GitHub Issues
• System Issues: Check Troubleshooting Guide
• Architecture Questions: Read Architecture Docs

---

Welcome to the team! 🎉