Saltar al contenido principal

Documentación Técnica

Documentación interna para el equipo de desarrollo y futuros contribuidores del ecosistema SwapBits

Tecnologías utilizadas

NestJS

Framework principal del backend

MongoDB

Base de datos principal

Redis

Cache y mensajería

Docker

Contenedorización y despliegue

AWS

Infraestructura cloud

Documentación Privada

Esta sección contiene información técnica interna del sistema SwapBits. El contenido aquí presentado está diseñado para:

  • Desarrolladores del equipo que necesitan entender la arquitectura
  • Nuevos integrantes que requieren onboarding técnico
  • Mantenimiento futuro del sistema
  • Decisiones técnicas y su documentación

No debe ser compartida públicamente sin autorización.

¿Qué encontrarás aquí?​

Esta documentación técnica está organizada en 8 categorías principales con 20+ documentos comprehensivos:

Índice de Documentación​

1. Visión General del Sistema​

Comprensión completa del ecosistema SwapBits y su arquitectura.

2. Microservicios​

Documentación detallada de todos los microservicios del sistema.

Core Services​

  • Core Services
    • Auth Service - Autenticación y autorización
    • User Service - Gestión de usuarios
    • Wallet Service - Gestión de wallets multi-blockchain
    • Bank Service - Operaciones bancarias

Business Services​

  • Business Services
    • Exchange Service - Trading y swaps
    • KYC Service - Verificación de identidad
    • Admin Service - Panel de administración

Communication Layer​

  • Communication Layer
    • WebSocket Service - Comunicación en tiempo real
    • Webhook Service - Notificaciones blockchain

Blockchain Infrastructure​

Shared Code​

  • Shared Packages
    • 30+ MongoDB Schemas compartidos
    • Guards, Interceptors, Middleware
    • Analytics, Chat, Rate Limiting

3. AWS Infrastructure​

Servicios cloud, serverless y gestión de infraestructura.

  • Lambda Functions Architecture

    • CreateWallet Functions (11 blockchains)
    • SendHotWallet Functions (Solana, Polkadot, TON)
    • Utilidades (Encrypt/Decrypt, Didit Integration)

  • AWS Secrets Manager

    • Gestión centralizada de secretos
    • JWT secrets, API keys, database credentials
    • Hot wallet private keys
    • Rotación automática y seguridad

  • EC2 Infrastructure

    • Configuración de instancias de producción
    • VPC, Security Groups, networking
    • Auto-scaling y load balancing
    • Deployment scripts y disaster recovery

4. Flujos de Negocio​

Documentación de flujos end-to-end del sistema.

5. Comunicación​

Patrones de comunicación entre servicios y clientes.

6. Arquitectura de Datos​

Estrategias de datos, schemas y migraciones.

7. Seguridad​

Implementaciones de seguridad en todas las capas.

8. Deployment & Operations​

Despliegue, monitoreo y mantenimiento.

Guías Rápidas​

  1. System Overview - Empezar aquí para entender el ecosistema completo
  2. System Architecture - Ver diagramas de arquitectura
  3. Microservices - Comprender los servicios core
  4. User Journey - Ver el flujo completo de un usuario
  5. Security - Entender las medidas de seguridad críticas

Para Entender un Flujo Específico​

Operaciones de Usuario:

Trading:

Desarrollo:

Para Operaciones y Deployment​

Stack Tecnológico​

Tecnologías Principales

Backend:

  • NestJS 11.x - Framework principal (TypeScript)
  • Node.js 18+ - Runtime
  • TypeScript - Lenguaje

Databases:

  • MongoDB 7.x - Base de datos principal (NoSQL)
  • Redis 7.x - Cache, sessions, Pub/Sub

Infrastructure:

  • Docker - Containerización
  • AWS Lambda - Funciones serverless
  • AWS Secrets Manager - Gestión de secrets
  • Nginx - Load balancer

Real-time:

  • Socket.io - WebSocket server
  • Redis Pub/Sub - Event streaming

Blockchain:

  • Ethers.js - EVM chains (Ethereum, BSC, Polygon)
  • @solana/web3.js - Solana
  • TronWeb - Tron
  • Bitcoin Core RPC - Bitcoin
  • TONConnect - TON
  • @polkadot/api - Polkadot
  • XRP Ledger - Ripple

External Services:

  • Bybit API - Exchange integration
  • Plaid - Bank verification
  • Didit - KYC/identity verification

Convenciones del Proyecto​

Estándares de Código

Naming Conventions:

  • Services: camelCase - userService, walletService
  • Controllers: PascalCase - UserController, AuthController
  • DTOs: PascalCase + Dto suffix - CreateUserDto, LoginDto
  • Schemas: PascalCase - User, Wallet, Transaction
  • Interfaces: PascalCase + I prefix - IUser, IWallet
  • Enums: PascalCase - TransactionStatus, WalletType

File Structure:

service-name/
├── src/
│   ├── controllers/      # HTTP endpoints
│   ├── services/         # Business logic
│   ├── dtos/            # Data Transfer Objects
│   ├── interfaces/      # TypeScript interfaces
│   ├── guards/          # Auth guards
│   ├── middleware/      # Custom middleware
│   └── index.ts         # Entry point
├── Dockerfile
├── package.json
└── tsconfig.json

Git Workflow:

  • main - Producción
  • develop - Development
  • feature/* - Nuevas features
  • fix/* - Bug fixes
  • hotfix/* - Hotfixes urgentes

Transferencia de Conocimiento​

Documentación para el Futuro

Esta documentación fue creada con el objetivo de transferir conocimiento del sistema completo a futuros desarrolladores. Incluso si los desarrolladores originales ya no están disponibles, cualquier desarrollador competente debería poder:

  1. Entender la arquitectura completa del sistema en pocas horas
  2. Hacer cambios seguros siguiendo los patrones establecidos
  3. Diagnosticar y resolver problemas usando las guías de troubleshooting
  4. Desplegar y mantener el sistema en producción
  5. Escalar y evolucionar el sistema según nuevas necesidades

Esta documentación es tu mejor compañero. Léela, mantenla actualizada, y compártela con todo el equipo.

Contribución a la Documentación​

Documentación Viva

Esta documentación es un documento vivo que debe evolucionar con el sistema:

Cuando actualizar:

  • [✓] Agregas un nuevo microservicio
  • [✓] Implementas un nuevo flujo de negocio
  • [✓] Cambias la arquitectura de seguridad
  • [✓] Actualizas el stack tecnológico
  • [✓] Modificas patrones de comunicación
  • [✓] Descubres un bug crítico o gotcha

Cómo contribuir:

  1. Edita directamente los archivos .md en docs/docs/technical/
  2. Usa Mermaid para diagramas (mermaid code blocks)
  3. Sigue la estructura establecida en cada categoría
  4. Agrega ejemplos prácticos y casos de uso
  5. Incluye troubleshooting cuando sea relevante
  6. Haz commit con mensaje descriptivo

Mantén consistencia:

  • Usa los mismos componentes de UI (InfoCard, TechStack)
  • Sigue la misma estructura de secciones
  • Mantén el tono técnico pero accesible
  • Agrega links a documentos relacionados

Contacto y Soporte​

Para preguntas técnicas o dudas sobre la arquitectura:

  • Documentación principal: Este sitio
  • Código fuente: GitHub Repository
  • Issues técnicos: GitHub Issues
  • Discusiones: GitHub Discussions

Última actualización: Octubre 2025

Versión del sistema: v2.0

Cobertura: 20+ documentos | 8 categorías | 13 microservicios | 18 Lambda functions