Developer Onboarding Guide¶

Welcome to the Feoda BI project. This guide covers everything you need to get from a fresh machine to a running development environment and your first commit.

Source Control Architecture

Azure Repos is the primary code repository. All developers push to Azure Repos using their individual Microsoft/Azure DevOps identity. An Azure Pipeline automatically mirrors code to GitHub for Copilot licensing and AI workflows. Developers never interact with GitHub directly.

Prerequisites¶

You need the following before starting:

Requirement	Purpose
Microsoft/Azure DevOps account	Individual identity for commits, PRs, and board access
Azure DevOps access	Added to the `Feoda_BI` project as a Contributor
Docker Desktop	Runs the Dev Container and service containers
VS Code	Primary IDE with Dev Container support
Dev Containers extension	VS Code extension for containerised development
GitHub Copilot license	AI-assisted coding (uses the GitHub mirror)

Individual Accounts Only

Every developer must use their own Microsoft/Azure DevOps identity. This ensures commits, PRs, and work item changes are individually attributed. Never share accounts.

Step 1: Install Docker Desktop¶

Download and install Docker Desktop for your OS.

# Verify installation
docker --version
docker compose version

Make sure Docker Desktop is running before proceeding.

Step 2: Install VS Code + Dev Containers Extension¶

Install VS Code if you don't have it
Install the Dev Containers extension from the Extensions marketplace (ms-vscode-remote.remote-containers)

Step 3: Clone the Repository¶

Clone from Azure Repos (the primary repository):

cd ~/Feoda
git clone https://dev.azure.com/feoda/Feoda_BI/_git/feoda-bi
cd feoda-bi

Git Credentials

When cloning for the first time, Azure DevOps will prompt for authentication. Options:

HTTPS + Git Credential Manager (recommended on macOS): Install GCM — it caches credentials automatically
SSH: Add an SSH key in Azure DevOps → User Settings → SSH public keys
Personal Access Token: Generate at Azure DevOps → User Settings → Personal access tokens (scope: Code > Read & Write)

Switch to the develop branch:

git checkout develop

Step 4: Open in Dev Container¶

Open the project in VS Code:

code .

VS Code will detect the .devcontainer/ configuration and prompt:

"Folder contains a Dev Container configuration file. Reopen folder to develop in a container?"

Click "Reopen in Container". VS Code will:

Build the Dev Container image (first time only, ~2–3 minutes)
Start PostgreSQL 16 and Redis 7 alongside the app container
Install all VS Code extensions (ESLint, Prettier, GitLens, Vitest, etc.)
Apply workspace settings (format on save, ESLint auto-fix)
Run npm install automatically
Open a terminal inside the container — ready to code

Git credentials from your host machine are automatically forwarded into the Dev Container.

Step 5: Verify Environment¶

Inside the Dev Container terminal, run:

# Node.js version (locked by Dev Container)
node --version   # Should show v22.x.x
npm --version    # Should show 10.x.x

# PostgreSQL (sibling container, accessed by service name)
PGPASSWORD=arm_dev_password psql -h postgres -U arm_dev -d arm_development -c "SELECT 1;"

# Redis (sibling container)
redis-cli -h redis ping   # Should return PONG

Service Hostnames

Inside the Dev Container, services are accessed by their Docker Compose service name — postgres and redis — not localhost. The .env.example file is pre-configured with these hostnames.

Step 6: Start the Development Server¶

npm run dev

The app starts at http://localhost:3000. Verify the health check:

curl http://localhost:3000/health

You should get a 200 OK response. API docs are available at http://localhost:3000/docs.

Step 7: Run Quality Checks¶

Before committing any code, verify all checks pass:

npm run lint        # ESLint
npm run type-check  # TypeScript compilation
npm test            # Vitest

Step 8: Create Your First Branch¶

All work is done on feature branches off develop. See the Branch Conventions for naming rules.

# Make sure you're on develop
git checkout develop
git pull origin develop

# Create a feature branch linked to a work item
git checkout -b feature/BI-17-database-migrations

Work item IDs come from Azure Boards. Check Boards → Backlogs for assigned stories.

Step 9: Commit and Push¶

Use the AB#<id> syntax in commit messages to auto-link to Azure Boards:

git add .
git commit -m "AB#17 Add initial tenant migration"
git push origin feature/BI-17-database-migrations

This will show the commit in the work item's Development tab in Azure Boards.

Step 10: Create a Pull Request¶

Go to Azure DevOps → Repos → Pull Requests → New pull request
Source: your feature branch → Target: develop
Fill in the PR template (summary, work items, changes, testing checklist)
Add a reviewer
The CI pipeline runs automatically — lint, type-check, and tests must pass

See Branch Conventions for the full PR workflow.

Available npm Scripts¶

Script	Purpose
`npm run dev`	Start dev server with hot reload
`npm run build`	Compile TypeScript to `dist/`
`npm run lint`	Run ESLint
`npm run format`	Auto-format with Prettier
`npm run type-check`	TypeScript type checking (no emit)
`npm test`	Run tests (Vitest)
`npm run test:watch`	Run tests in watch mode
`npm run migrate`	Run database migrations
`npm run seed`	Seed development data

Project Structure¶

feoda-bi/
├── .devcontainer/         ← Dev Container config (Node 22, PostgreSQL, Redis)
├── .azuredevops/          ← PR template
├── src/
│   ├── app.ts             ← Fastify app setup
│   ├── server.ts          ← Entry point
│   ├── config/            ← Environment config loader
│   ├── modules/           ← Feature modules (health, tenants, billing, etc.)
│   ├── database/          ← Migrations and seeds
│   ├── middleware/        ← Auth, error handling
│   ├── plugins/           ← Fastify plugins (postgres, redis, swagger)
│   └── utils/             ← Logger, errors, pagination
├── tests/                 ← Test files
├── azure-pipelines.yml    ← CI pipeline
├── tsconfig.json
├── .eslintrc.json
├── .prettierrc
└── .env.example           ← Environment variable template

Fallback: Without Dev Containers¶

If you cannot use Dev Containers (e.g., JetBrains IDE), the repo includes fallback safeguards:

nvm use                    # Reads .nvmrc, switches to Node 22
npm install                # Fails if Node version doesn't match engines
docker compose up -d       # Starts PostgreSQL + Redis
cp .env.example .env       # Create local env file
npm run dev                # Starts the app

Dev Containers Preferred

The Dev Container is the primary development method. It guarantees identical environments across the team — same Node.js version, same tools, same extensions, same OS. Use the fallback only if necessary.

Key Resources¶

Resource	Location
Azure Boards	dev.azure.com/feoda/Feoda_BI
Azure Repos	dev.azure.com/feoda/Feoda_BI/_git/feoda-bi
Branch Conventions	branch-conventions.md
Code Conventions	code-conventions.md
Technology Stack	Technology Stack Comparison
Implementation Kickoff	Implementation Kickoff Guide