AMISPHERE - DOCUMENTATION TECHNIQUE
═══════════════════════════════════════════════════════════════

Architecture Décentralisée & Fédération


1. ARCHITECTURE GLOBALE
═══════════════════════════════════════════════════════════════

┌─────────────────────────────────────────────────────────────┐
│                    AMISPHERE ECOSYSTEM                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                 │
│  │   Hub        │◄────────┤  Instance A  │                 │
│  │  Central     │         │  (Entreprise)│                 │
│  │ amisphere.com│────────►└──────────────┘                 │
│  └──────┬───────┘                                           │
│         │                                                    │
│         ├────────►┌──────────────┐                         │
│         │         │  Instance B  │                         │
│         │         │    (École)   │                         │
│         │         └──────────────┘                         │
│         │                                                    │
│         └────────►┌──────────────┐                         │
│                   │  Instance C  │                         │
│                   │     (ONG)    │                         │
│                   └──────────────┘                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘


2. MODÈLE HUB-AND-SPOKE
═══════════════════════════════════════════════════════════════

PRINCIPE :
• Hub central = Serveur principal AmiSphere
• Spokes = Instances autonomes (organisations)
• Communication bidirectionnelle via API REST + WebSocket

AVANTAGES :
✓ Simple à implémenter
✓ Sécurisé (authentification centralisée)
✓ Évolutif horizontalement
✓ Souveraineté des données garantie
✓ Interopérabilité native


3. STACK TECHNIQUE
═══════════════════════════════════════════════════════════════

BACKEND :
• Node.js 20+ (LTS)
• Express.js (API REST)
• Socket.io (WebSocket temps réel)
• MySQL 8.0 (données structurées)
• Redis (cache + pub/sub)

FRONTEND :
• React Native (Expo SDK 54) - Mobile iOS/Android
• React.js - Web
• TypeScript recommandé

SÉCURITÉ :
• Chiffrement : AES-256-GCM
• Authentification : JWT + Refresh Tokens
• HTTPS/TLS obligatoire
• Rate limiting multi-niveaux

HÉBERGEMENT :
• VPS Ubuntu 24 LTS
• Nginx reverse proxy
• PM2 process manager
• Backups automatiques quotidiens


4. API DE FÉDÉRATION
═══════════════════════════════════════════════════════════════

ENDPOINTS PRINCIPAUX :

POST /api/federation/register-instance
  → Enregistrer nouvelle instance
  Body: { domain, publicKey, adminEmail }
  Response: { instanceId, apiKey }

POST /api/federation/send-message
  → Envoyer message cross-instance
  Headers: { Authorization: Bearer {apiKey} }
  Body: { fromUserId, toUserId, content, encrypted }

GET /api/federation/users/search
  → Rechercher utilisateurs externes
  Query: { query, instanceId }

POST /api/federation/webhook
  → Recevoir événements temps réel
  Body: { event, data, signature }


5. AUTHENTIFICATION INTER-INSTANCES
═══════════════════════════════════════════════════════════════

OAUTH 2.0 FLOW :

1. Instance B veut communiquer avec Instance A
2. Instance B demande token au Hub central
3. Hub valide identité Instance B (API key + signature)
4. Hub génère JWT temporaire (1h)
5. Instance B utilise JWT pour API calls
6. Refresh automatique avant expiration


SÉCURITÉ :
• API Keys 256-bit générées aléatoirement
• Public/Private key pairs (RSA 4096)
• Signature HMAC-SHA256 sur chaque requête
• Whitelist domaines autorisés


6. TABLES BDD FÉDÉRATION
═══════════════════════════════════════════════════════════════

-- Instances fédérées
CREATE TABLE federated_instances (
    id CHAR(36) PRIMARY KEY,
    domain VARCHAR(255) UNIQUE,
    api_key VARCHAR(255),
    public_key TEXT,
    status ENUM('active', 'suspended', 'pending'),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_sync_at TIMESTAMP
);

-- Utilisateurs externes
CREATE TABLE external_users (
    id CHAR(36) PRIMARY KEY,
    instance_id CHAR(36),
    external_user_id VARCHAR(255),
    username VARCHAR(255),
    avatar_url TEXT,
    public_key TEXT,
    metadata JSON,
    FOREIGN KEY (instance_id) REFERENCES federated_instances(id)
);

-- Messages cross-instance
CREATE TABLE federated_messages (
    id CHAR(36) PRIMARY KEY,
    from_instance_id CHAR(36),
    to_instance_id CHAR(36),
    message_hash VARCHAR(255),
    delivered_at TIMESTAMP,
    acknowledged_at TIMESTAMP,
    FOREIGN KEY (from_instance_id) REFERENCES federated_instances(id),
    FOREIGN KEY (to_instance_id) REFERENCES federated_instances(id)
);


7. ROUTAGE MESSAGES
═══════════════════════════════════════════════════════════════

DÉTECTION DESTINATION :

function routeMessage(message) {
  const recipient = message.toUserId;
  
  // Format : userId@instance.domain
  if (recipient.includes('@')) {
    const [userId, domain] = recipient.split('@');
    
    if (domain === 'amisphere.com') {
      // Message local
      return deliverLocal(message);
    } else {
      // Message externe
      return deliverFederated(message, domain);
    }
  } else {
    // Par défaut : local
    return deliverLocal(message);
  }
}


8. CHIFFREMENT BOUT-EN-BOUT
═══════════════════════════════════════════════════════════════

INTER-INSTANCES :

1. Utilisateur A génère paire clés (RSA)
2. Clé publique stockée sur son instance
3. Hub central synchronise clés publiques
4. Message chiffré avec clé publique destinataire
5. Seul destinataire peut déchiffrer (clé privée)

ALGORITHMES :
• RSA-4096 : Échange clés
• AES-256-GCM : Chiffrement messages
• SHA-256 : Hashing
• HMAC-SHA256 : Signatures


9. REDIS PUB/SUB
═══════════════════════════════════════════════════════════════

ÉVÉNEMENTS TEMPS RÉEL :

// Publisher (message.service.js)
await redis.publish('message:new', JSON.stringify({
  toUserId: '123@external.com',
  fromUserId: 'alice@amisphere.com',
  content: 'encrypted_data',
  timestamp: Date.now()
}));

// Subscriber (websocket/server.js)
redis.subscribe('message:new');
redis.on('message', (channel, data) => {
  const event = JSON.parse(data);
  
  if (event.toUserId.includes('@')) {
    // Routage externe
    federationService.deliverExternal(event);
  } else {
    // Local WebSocket
    io.to(`user:${event.toUserId}`).emit('message:new', event);
  }
});


10. DÉPLOIEMENT INSTANCE TIERCE
═══════════════════════════════════════════════════════════════

PRÉREQUIS :
• Ubuntu 24 LTS
• 2 vCPU minimum
• 4 Go RAM minimum
• 50 Go SSD
• Nom de domaine (SSL obligatoire)

INSTALLATION :

# 1. Cloner repository
git clone https://github.com/amisphere/server.git
cd server

# 2. Configuration
cp .env.example .env
nano .env  # Éditer avec vos paramètres

# 3. Installation dépendances
npm install

# 4. Setup base de données
mysql -u root -p < schema.sql

# 5. Démarrage
pm2 start server.js --name amisphere-instance

# 6. Enregistrement au Hub
curl -X POST https://amisphere.com/api/federation/register-instance \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "votre-instance.com",
    "adminEmail": "admin@votre-instance.com",
    "publicKey": "....."
  }'


11. MONITORING & OBSERVABILITÉ
═══════════════════════════════════════════════════════════════

MÉTRIQUES CLÉS :
• Messages/seconde (local + fédération)
• Latence API (p50, p95, p99)
• Taux erreur fédération
• Uptime instances externes
• Queue size Redis

OUTILS :
• Winston : Logs structurés
• Prometheus : Métriques temps réel
• Grafana : Dashboards
• Sentry : Error tracking


12. ÉVOLUTION VERS FÉDÉRATION COMPLÈTE
═══════════════════════════════════════════════════════════════

ROADMAP :

Phase 1 (Actuelle) : Hub-and-Spoke
✓ Hub central obligatoire
✓ Instances communiquent via Hub
✓ Simplicité > Décentralisation

Phase 2 (6-12 mois) : Fédération partielle
○ Instances peuvent se parler directement
○ Hub devient optionnel (discovery)
○ Protocole ActivityPub compatible

Phase 3 (12-24 mois) : Fédération complète
○ Peer-to-peer entre instances
○ Pas de point central
○ Réseau maillé distribué


13. COÛTS HÉBERGEMENT
═══════════════════════════════════════════════════════════════

INSTANCE PETITE (< 1000 utilisateurs) :
• VPS : 10-20€/mois
• Base de données : inclus
• Bande passante : ~500 Go/mois
• Total : ~15€/mois

INSTANCE MOYENNE (1000-10000 utilisateurs) :
• VPS : 40-80€/mois
• Redis : 15€/mois
• CDN : 20€/mois
• Total : ~75€/mois

INSTANCE GRANDE (10000+ utilisateurs) :
• Cluster : 200-500€/mois
• Load balancer : 30€/mois
• CDN : 100€/mois
• Monitoring : 50€/mois
• Total : ~400€/mois


14. SUPPORT & COMMUNAUTÉ
═══════════════════════════════════════════════════════════════

RESSOURCES :
• Documentation : docs.amisphere.com
• Forum : community.amisphere.com
• GitHub : github.com/amisphere
• Discord : discord.gg/amisphere

CONTRIBUTION :
• Code open source (licence AGPL v3)
• PRs bienvenues
• Issues & feature requests
• Traductions communautaires


═══════════════════════════════════════════════════════════════

Version : 1.0
Dernière mise à jour : Novembre 2025
Contact technique : tech@amisphere.com