Finitech — FinTech Platform Architecture

Architecture .NET 8 complète pour une plateforme FinTech couvrant Banking, Wallet et Paiements avec séparation stricte des domaines, sécurité enterprise-grade et conformité réglementaire.

Pourquoi Modular Monolith ?

Raison	Détail
Cohérence transactionnelle	Le ledger immuable nécessite des transactions ACID strictes
Performance	Pas de latence réseau des appels inter-services
Simplicité opérationnelle	Un seul déploiement, un seul monitoring
Migration progressive	Décomposable en microservices si nécessaire

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          API HOST                               │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  ┌─────────────┐│
│  │ Banking  │  │  Wallet  │  │ WalletFMCG   │  │   Ledger    ││
│  │  🟢      │  │  🟢      │  │  🟠          │  │   🟢        ││
│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  └──────┬──────┘│
│       └─────────────┴───────────────┴──────────────────┘       │
│                              │                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │Payments  │  │    FX    │  │Statements│  │MerchantPay   │   │
│  │  🟡      │  │  🟡      │  │  🟠      │  │  🟡          │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬───────┘   │
│       └─────────────┴─────────────┘                │            │
│                     │                              │            │
│  ┌──────────┐  ┌────────────┐  ┌──────────┐  ┌────┴─────┐     │
│  │PartyReg. │  │ Identity   │  │Compliance│  │Disputes  │     │
│  │  🟢      │  │  🟢        │  │  🟠      │  │  🟡      │     │
│  └──────────┘  └────────────┘  └──────────┘  └──────────┘     │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │Notifs    │  │Budgeting │  │  Audit   │  │  Documents   │   │
│  │  🟡      │  │  🟡      │  │  🟠      │  │  🟠          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              BuildingBlocks                             │   │
│  │   Domain · Application · Infrastructure · SharedKernel  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

🟢 Implemented   🟡 Service Layer   🟠 Contracts   ⚪ Scaffold

Règles de dépendances strictes :

❌ Banking ne référence JAMAIS Wallet ou WalletFMCG
❌ Wallet ne référence JAMAIS Banking
✅ Les deux référencent les modules communs (Ledger, Payments, FX, PartyRegistry)
✅ Communication inter-modules uniquement via Contracts (interfaces + DTOs)
✅ Domain ne dépend jamais d'Infrastructure (Clean Architecture)

Les 18 Modules

Core — Implémentés 🟢

Module	Rôle	Fonctionnalités
Ledger	Source de vérité financière	Double-entry bookkeeping, multi-devise, outbox pattern, historique immutable
Identity	Authentification	JWT RSA-2048, refresh tokens avec rotation, MFA/TOTP, sessions
Banking	Comptes bancaires	Comptes épargne, prêts, découvert, calcul d'intérêts, cartes
Wallet	Portefeuille digital	P2P, split payments, loyalty, Orange Money/Inwi Money, paiement factures, KYC 4 niveaux, offres/promotions, détection fraude
PartyRegistry	Référentiel clients	Parties (Individual/Organization), rôles multi-domaines

Services — Application Layer 🟡

Module	Rôle	Fonctionnalités
Payments	Virements	Intra-devise, cross-devise via FX, ordres permanents
FX	Change	Taux de change temps réel (simulé), quotes 5min, conversion MAD/EUR/USD
MerchantPayments	Paiement marchand	QR EMVCo dynamique, paiement par scan, ISO 4217
Disputes	Litiges	Remboursements partiels/totaux, chargebacks
Notifications	Alertes	Routing SMS/Email/Push, templates
Budgeting	Gestion budget	Catégorisation, budgets mensuels, analytics de dépenses, alertes seuil

Contracts définis 🟠

Module	Rôle
IdentityCompliance	eKYC, KYB, AML, détection fraude, freeze/unfreeze
Statements	Relevés comptables périodiques
WalletFMCG	Distribution agents, cash-in/cash-out, commissions
Audit	Audit trail pour compliance
Documents	Stockage documents (S3 compatible)
BranchNetwork	Gestion des agences
Scheduler	Jobs planifiés (Quartz.NET)

Stack Technique

Composant	Technologie
Runtime	.NET 8.0
Database	PostgreSQL 2022
ORM	Entity Framework Core + Migrations
Auth	JWT RSA-2048 signing
Passwords	Argon2id (OWASP recommended)
Encryption	AES-256-GCM pour PII
MFA	TOTP (Google/Microsoft Authenticator)
Cards	Tokenization PCI-compliant
Background Jobs	Quartz.NET
API Docs	OpenAPI / Swagger
Tests	xUnit + NetArchTest.Rules
Observabilité	OpenTelemetry + Prometheus
Containers	Docker + Docker Compose
Orchestration	Kubernetes (Kustomize)
CI/CD	GitHub Actions

Quick Start

Prérequis

Docker Desktop
.NET 8 SDK

1. Démarrer PostgreSQL

docker-compose up -d postgres

2. Lancer l'application

dotnet run --project src/ApiHost/Finitech.ApiHost/Finitech.ApiHost.csproj

→ API : http://localhost:5000 → Swagger : http://localhost:5000/swagger

3. Tout en Docker

docker-compose up --build

Exemples d'utilisation

Créer un client

curl -X POST http://localhost:5000/api/partyregistry \
  -H "Content-Type: application/json" \
  -d '{
    "partyType": "Individual",
    "firstName": "Ahmed",
    "lastName": "Benali",
    "email": "ahmed@example.com",
    "phoneNumber": "+212612345678",
    "initialRoles": ["Consumer", "RetailCustomer"]
  }'

Obtenir un taux de change

curl -X POST http://localhost:5000/api/fx/rate \
  -H "Content-Type: application/json" \
  -d '{"fromCurrencyCode": "MAD", "toCurrencyCode": "EUR"}'

Envoi P2P Wallet

curl -X POST http://localhost:5000/api/wallet/p2p/send \
  -H "Content-Type: application/json" \
  -d '{
    "fromWalletId": "{walletId}",
    "toIdentifier": "+212612345679",
    "identifierType": "Phone",
    "currencyCode": "MAD",
    "amountMinorUnits": 25000,
    "idempotencyKey": "p2p-001"
  }'

Générer un QR EMVCo

curl -X POST http://localhost:5000/api/merchantpayments/qr/generate \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "{merchantId}",
    "currencyCode": "MAD",
    "amountMinorUnits": 15000,
    "reference": "CMD-001"
  }'

→ Tous les endpoints : docs/API-REFERENCE.md

Sécurité

Protection	Implémentation
Authentication	JWT RSA-2048, access token 15min, refresh 7j avec rotation
Passwords	Argon2id (OWASP)
Data	AES-256-GCM encryption pour PII
Cards	Tokenization PCI-compliant
MFA	TOTP compatible Google/Microsoft Authenticator
Rate Limiting	100 req/min global, 5 req/5min auth
Headers	CSP, HSTS, X-Frame-Options, X-Content-Type-Options

→ Détails : SECURITY.md

Multi-Devise

Le système supporte MAD, EUR, USD nativement :

Stockage en minor units (long) + CurrencyCode (string)
Conversion via module FX avec taux simulés (provider-ready pour production)
Ledger : une écriture par devise, pas de conversion implicite
QR EMVCo : devise numérique ISO 4217 (504=MAD, 978=EUR, 840=USD)

Tests

# Tests unitaires (FX, Disputes, MerchantPayments, Budgeting, Money, Outbox)
dotnet test tests/Finitech.UnitTests

# Tests d'architecture (vérifie les dépendances inter-modules)
dotnet test tests/Finitech.ArchitectureTests

# Tests d'intégration (nécessite PostgreSQL)
docker-compose up -d postgres
dotnet test tests/Finitech.IntegrationTests

Les tests d'architecture vérifient automatiquement :

❌ Banking ne référence pas Wallet
❌ Wallet ne référence pas Banking
✅ Modules communiquent via Contracts uniquement
✅ Domain ne dépend pas d'Infrastructure

Déploiement Kubernetes

# Staging
kubectl apply -k k8s/overlays/staging

# Production
kubectl apply -k k8s/overlays/production

Inclut : Deployment, Service, Ingress, ConfigMap, NetworkPolicy, ServiceAccount.

Structure du projet

Finitech/
├── src/
│   ├── ApiHost/                    # ASP.NET Core host (controllers, config)
│   ├── BuildingBlocks/             # Shared kernel (Domain, Application, Infrastructure)
│   │   ├── Domain/                 # Interfaces, repositories, Result pattern
│   │   ├── Application/            # CQRS patterns
│   │   ├── Infrastructure/         # EF Core, JWT, Argon2, AES, Outbox
│   │   ├── SharedKernel/           # Money, Entity, ValueObject, AggregateRoot
│   │   └── Contracts/              # DTOs partagés
│   └── Modules/                    # 18 modules métier
│       ├── Banking/                # Comptes, prêts, cartes, intérêts
│       ├── Wallet/                 # P2P, loyalty, paiements programmés
│       ├── Ledger/                 # Double-entry bookkeeping
│       ├── Payments/               # Virements intra/cross-devise
│       ├── FX/                     # Change, quotes, conversion
│       ├── MerchantPayments/       # QR EMVCo
│       ├── PartyRegistry/          # Référentiel clients
│       ├── Identity*/              # Auth JWT + MFA
│       ├── IdentityCompliance/     # eKYC, AML
│       └── ...                     # Notifications, Budgeting, Disputes, etc.
├── tests/
│   ├── UnitTests/                  # 9 fichiers de tests
│   ├── ArchitectureTests/          # Tests de dépendances
│   └── IntegrationTests/           # Tests avec PostgreSQL
├── k8s/                            # Kubernetes (Kustomize)
├── docs/                           # API Reference
├── docker-compose.yml
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

💳 Wallet — Fonctionnalités ZOUZ (fusionnées)

Le module Wallet intègre désormais toutes les fonctionnalités de ZOUZ.Wallet :

Méthodes de paiement marocaines

Méthode	Provider
Carte bancaire	Payment Gateway
Virement bancaire	Bank Transfer API
Orange Money	`api.orangemoney.ma`
Inwi Money	`api.inwimoney.ma`
Cash (via agent)	En agence

Paiement de factures

Type	Fournisseurs
Télécom	Maroc Telecom, Inwi, Orange
Eau	REDAL, LYDEC
Électricité	ONEE
Taxes	Direction Générale des Impôts

KYC 4 niveaux (Bank Al-Maghrib)

Niveau	Vérification	Limite/jour	Limite/mois
None	Aucune	0 MAD	0 MAD
Basic	Téléphone + Email	2,000 MAD	10,000 MAD
Standard	CIN (Carte d'Identité Nationale)	10,000 MAD	50,000 MAD
Advanced	Vérification complète	20,000 MAD	100,000 MAD

Offres & Promotions (5 types)

Cashback · Réduction de frais · Bonus recharge · Programme fidélité · Promotions spéciales

Détection de fraude

Règles basées sur les seuils Bank Al-Maghrib : dépôts >10,000 MAD, retraits >5,000 MAD, transferts >7,000 MAD, cash >5,000 MAD.

Roadmap

✅ Complété

🔄 Prochaines étapes

Event sourcing pour le Ledger (append-only event store, jsonb)
RabbitMQ pour outbox distribué (Transactional Outbox Pattern)
API Gateway Traefik v3 (rate limiting, CORS, security headers)
Multi-région
Fusion ZOUZ.Wallet — KYC, factures, offres, fraude, Orange/Inwi Money
Dashboard admin React

Documentation

Document	Contenu
API Reference	Tous les endpoints (30+ routes)
Security	Politique de sécurité et features
Contributing	Setup, conventions, PR process
Architecture	Décisions techniques détaillées

Licence

MIT — Khalil Benazzouz

Event Sourcing (Ledger)

Le module Ledger utilise l'Event Sourcing pour garantir une traçabilité complète :

Domain Event → Outbox Table (même transaction) → RabbitMQ → Consumers

Chaque opération financière est un événement immutable stocké en PostgreSQL jsonb :

Event Type	Description
`AccountOpened`	Ouverture de compte
`MoneyDeposited`	Dépôt
`MoneyWithdrawn`	Retrait
`TransferExecuted`	Virement
`InterestAccrued`	Intérêts calculés
`FxConversionExecuted`	Conversion de devise
`RefundProcessed`	Remboursement
`ChargebackInitiated`	Chargeback

L'état d'un compte peut être reconstruit à tout moment en rejouant ses événements.

API Gateway (Traefik)

# Lancer avec le gateway
docker-compose -f docker-compose.yml -f gateway/docker-compose.gateway.yml up

Fonctionnalités :

Rate limiting (100 req/min)
CORS configuré
Security headers (HSTS, CSP, X-Frame-Options)
Dashboard : http://localhost:8080

Message Broker (RabbitMQ)

Le Transactional Outbox Pattern garantit la livraison fiable des événements :

L'événement est écrit dans la table outbox dans la même transaction que le changement
Le OutboxProcessor (background job) lit les messages pending
Publication vers RabbitMQ avec retry automatique (max 5 tentatives)
Marquage comme Published après succès

Dashboard RabbitMQ : http://localhost:15672 (finitech/finitech)

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
gateway		gateway
k8s		k8s
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Directory.Build.props		Directory.Build.props
Finitech.sln		Finitech.sln
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

Finitech — FinTech Platform Architecture

Pourquoi Modular Monolith ?

Architecture

Les 18 Modules

Core — Implémentés 🟢

Services — Application Layer 🟡

Contracts définis 🟠

Stack Technique

Quick Start

Prérequis

1. Démarrer PostgreSQL

2. Lancer l'application

3. Tout en Docker

Exemples d'utilisation

Créer un client

Obtenir un taux de change

Envoi P2P Wallet

Générer un QR EMVCo

Sécurité

Multi-Devise

Tests

Déploiement Kubernetes

Structure du projet

💳 Wallet — Fonctionnalités ZOUZ (fusionnées)

Méthodes de paiement marocaines

Paiement de factures

KYC 4 niveaux (Bank Al-Maghrib)

Offres & Promotions (5 types)

Détection de fraude

Roadmap

✅ Complété

🔄 Prochaines étapes

Documentation

Licence

Event Sourcing (Ledger)

API Gateway (Traefik)

Message Broker (RabbitMQ)

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages