Developer Onboarding Guide

Welcome to Almafrica! This guide will get you from zero to productive contributor.

First Day Checklist

• Get access to GitHub repository
• Get access to staging environment
• Set up local development environment
• Run the project locally
• Complete your first small task

Prerequisites

Before you start, ensure you have these tools installed:

Tool	Version	Purpose
.NET SDK	10.0	Backend development
Node.js	20.x LTS	Web development
pnpm	9.x	Package management
Flutter	3.x	Mobile development
Docker	Latest	Local databases
PostgreSQL	15.x	Database (or use Docker)
Git	2.x	Version control

Recommended Tools

• IDE: VS Code, Rider, or Visual Studio
• API Testing: Postman or Insomnia
• Database: pgAdmin or DBeaver
• Terminal: iTerm2 (macOS) or Windows Terminal

See Prerequisites Guide for detailed installation instructions.

Project Structure Overview

Almafrica/
├── backend/              # .NET Backend API
│   ├── Almafrica.API/           # Controllers, middleware
│   ├── Almafrica.Application/   # Business logic, DTOs
│   ├── Almafrica.Domain/        # Entities, enums
│   ├── Almafrica.Infrastructure/# Data access, external services
│   └── Almafrica.Tests/         # Test projects
│
├── web/almafrica-web/    # Next.js Web Dashboard
│   ├── src/app/                 # App Router pages
│   ├── src/components/          # React components
│   └── src/lib/                 # API clients, stores
│
├── mobile/mon_jardin/    # Flutter Mobile App
│   ├── lib/core/                # Config, services
│   ├── lib/data/                # Repositories, models
│   ├── lib/domain/              # Business entities
│   └── lib/presentation/        # Screens, widgets
│
├── docs/                 # Documentation (you are here)
├── agent-os/             # Agent-focused specs & standards
└── infrastructure/       # Deployment configs

Quick Start

1. Clone and Setup

git clone <repository-url>
cd Almafrica

# Copy environment files
cp .env.production.example .env
cp backend/.env.example backend/.env
cp web/almafrica-web/.env.example web/almafrica-web/.env.local

2. Start Dependencies

# Start PostgreSQL and other services
docker-compose -f docker-compose.local.yml up -d

3. Start Backend

cd backend

# Restore packages
dotnet restore

# Run migrations
dotnet ef database update --project Almafrica.Infrastructure --startup-project Almafrica.API

# Start the API
dotnet run --project Almafrica.API

Backend runs at: http://localhost:5000

4. Start Web Dashboard

cd web/almafrica-web

# Install dependencies
pnpm install

# Start development server
pnpm dev

Web runs at: http://localhost:3000

5. Start Mobile App (Optional)

cd mobile/mon_jardin

# Get dependencies
flutter pub get

# Run on connected device/simulator
flutter run

Architecture Overview

Backend (.NET Clean Architecture)

┌─────────────────────────────────────────────────────────────┐
│                     Almafrica.API                           │
│         Controllers, Middleware, Validators                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Almafrica.Application                       │
│         Services, DTOs, Interfaces, Mappings                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Almafrica.Domain                          │
│         Entities, Enums, Domain Events                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                Almafrica.Infrastructure                     │
│         DbContext, Repositories, Migrations                 │
└─────────────────────────────────────────────────────────────┘

Key Conventions:

• Controllers are thin - business logic lives in services
• Use the Result<T> pattern for operation outcomes
• All database changes require migrations with Down() methods

Web Dashboard (Next.js 15)

┌─────────────────────────────────────────────────────────────┐
│                       src/app/                              │
│         App Router pages, layouts, loading states           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   src/components/                           │
│         UI components, forms, modals                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      src/lib/                               │
│         API clients, Zustand stores, Zod schemas            │
└─────────────────────────────────────────────────────────────┘

Key Conventions:

• Use server components by default, client components only when needed
• State management via Zustand stores
• Form validation via Zod schemas

Mobile App (Flutter)

┌─────────────────────────────────────────────────────────────┐
│                   lib/presentation/                         │
│         Screens, widgets, providers                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     lib/domain/                             │
│         Entities, repository interfaces, use cases          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      lib/data/                              │
│         Models, repositories, datasources (local/remote)    │
└─────────────────────────────────────────────────────────────┘

Key Conventions:

• Offline-first: all data stored in SQLite, synced when online
• Provider for dependency injection and state management
• Clean architecture with clear layer separation

Domain Concepts

Almafrica manages agricultural operations. Key entities:

Entity	Description
Farmer	Individual farmers registered in the system
Farm	Farm belonging to a farmer
Field Agent	Field workers who visit farmers
Assessment	Quality assessments of farmer/farm conditions
Stock	Inventory at collection centers
Transfer	Movement of stock between centers
Collection Center	Where produce is collected and managed

See Glossary for complete terminology.

Development Workflow

Branch Naming

feature/ABC-123-description    # New features
fix/ABC-456-description        # Bug fixes
chore/description              # Maintenance tasks

Commit Messages

ABC-123: Add farmer export functionality

- Add CSV export endpoint
- Add export button to farmer list
- Include pagination for large exports

Before Pushing

Run these commands for your affected layer:

# Backend
dotnet build Almafrica.sln
dotnet test Almafrica.sln

# Web
npm run type-check
npm run lint
npm run test
npm run build

# Mobile
flutter analyze
flutter test

Getting Help

1. Check documentation - You're here, good start!
2. Search existing issues - Your question may be answered
3. Ask in team chat - #engineering channel
4. Create an issue - For bugs or documentation gaps

Next Steps

• Read the Architecture Overview
• Review Development Workflow
• Pick up a "good first issue" from GitHub
• Shadow a code review to learn conventions