Architecture Overview
High-level system architecture for Almafrica. For deeper system walkthroughs, continue into the n8n workflow architecture docs and the operational guides linked below.
System Context
Almafrica is an agricultural management platform serving three user groups:
┌─────────────────────────────────────────────────────────────────┐
│ Almafrica System │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Mobile │ │ Web │ │ Backend │ │
│ │ App │◄──►│ Dashboard │◄──►│ API │ │
│ │ (Flutter) │ │ (Next.js) │ │ (.NET Core) │ │
│ └─────────────┘ └─────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ PostgreSQL │ │
│ │ Database │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
Field Agents Managers System
(Offline-first) (Reporting) Administrators
Key Architectural Decisions
1. Clean Architecture (Backend)
The backend follows Clean Architecture with dependency inversion:
┌──────────────────────────────────────────────────┐
│ API Layer │
│ Controllers, Middleware, DTOs │
├──────────────────────────────────────────────────┤
│ Application Layer │
│ Services, Interfaces, Use Cases │
├──────────────────────────────────────────────────┤
│ Domain Layer │
│ Entities, Enums, Domain Events │
├──────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ Repositories, DbContext, Migrations │
└──────────────────────────────────────────────────┘
Dependencies flow inward (↓)
2. Offline-First (Mobile)
The mobile app works without internet:
┌─────────────────────────────────────────────────┐
│ Mobile App │
├─────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────────────┐ │
│ │ UI Layer │◄────►│ Local SQLite │ │
│ │ (Screens) │ │ (Primary Source) │ │
│ └─────────────┘ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Sync Service │ │
│ │ (When Online) │ │
│ └──────────┬──────────┘ │
└──────────────────────────────────┼──────────────┘
│
▼
Backend API
3. Server Components (Web)
The web dashboard uses Next.js 15 with React Server Components:
┌─────────────────────────────────────────────────┐
│ Web Dashboard │
├─────────────────────────────────────────────────┤
│ Server Components Client Components │
│ - Data fetching - Interactivity │
│ - SEO - State │
│ - Security - Animations │
├─────────────────────────────────────────────────┤
│ Shared Layer │
│ - Zustand Stores │
│ - Zod Schemas │
│ - API Client │
└─────────────────────────────────────────────────┘
Data Flow
Online Flow
User Action → API Request → Backend Service → Database → Response
Offline Flow (Mobile)
User Action → Local SQLite → Sync Queue → (When Online) → API
Security Architecture
┌─────────────────────────────────────────────────┐
│ Security Layers │
├─────────────────────────────────────────────────┤
│ Authentication JWT tokens, OAuth providers │
│ Authorization Role-based access control │
│ Input Validation Zod/FluentValidation │
│ Data Protection Encryption at rest/transit │
│ API Security Rate limiting, CORS │
└─────────────────────────────────────────────────┘
Deployment Architecture
┌─────────────────────────────────────────────────────────────┐
│ Production │
├─────────────────────────────────────────────────────────────┤
│ Load Balancer │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ API-1 API-2 ──► PostgreSQL (Primary + Replica) │
│ │ │ │
│ └────┬────┘ │
│ │ │
│ Web Dashboard (CDN) │
│ │ │
│ Mobile Apps (App Stores) │
└─────────────────────────────────────────────────────────────┘
Detailed Documentation
- n8n Workflow Overview - Cross-domain workflow map
- Authentication & Authorization - Identity, JWT, and permissions
- Data Sync Engine - Offline-first sync architecture
- Farmer Management - Core field data workflows
- Warehouse & Stock - Inventory movement lifecycle
Suggested Reading Order
- Start with n8n Workflow Overview for the system map
- Continue with Authentication & Authorization and Data Sync Engine for the cross-cutting platform behavior
- Then jump into the operational domain you care about most:
Technology Decisions
| Decision | Rationale |
|---|---|
| .NET Core | Enterprise-grade, strong typing, excellent tooling |
| PostgreSQL | Reliability, JSON support, full-text search |
| Next.js 15 | Server components, excellent DX, SEO-friendly |
| Flutter | Single codebase, offline-first support, performance |
| Clean Architecture | Testability, maintainability, separation of concerns |
Evolution
Key architectural evolution points:
- Phase 1: Monolithic API, basic web dashboard
- Phase 2: Offline-first mobile app, sync infrastructure
- Phase 3: Server components, performance optimization
- Current: Production-ready, scalable architecture