System Architecture Overview

The MyNATCA ecosystem is a modern, scalable platform built with a microservices architecture that provides secure member management, API integration, and community features.

Current Implementation Architecture

Core Components

1. Platform Infrastructure (`mynatca-platform`)

The central foundation that provides:

Data Synchronization Engine: Reliable transfer from MySQL to Supabase
Shared Database Schema: PostgreSQL with Row Level Security
Common Utilities: TypeScript types, Auth0 helpers, API clients
Development Tools: Claude Code agents, migration tools

Key Features:

Dependency-aware sync orchestration
Batch processing with error isolation
Comprehensive retry logic and health monitoring
Real-time subscriptions and edge functions

2. Discord Bot (`mynatca-discord`)

Discord integration for member verification and community management:

OAuth Verification System: Auth0-based member linking
Role Management: Automatic assignment based on positions
Real-time Updates: Webhook support for member changes
Administrative Tools: Manual verification and account management

Key Features:

Secure member verification via Auth0
Position-based role assignment (FacRep, NEB, etc.)
Facility and region role management
Comprehensive audit logging

3. Member Hub (`mynatca-hub`)

Vue.js web application for member self-service:

Member Portal: Profile management and information access
Self-Service Tools: Update contact information, view positions
Integration Dashboard: Connected account management
Responsive Design: Mobile-first approach

4. Document Management System (`mynatca-dms`)

Organizational document storage and management:

Document Repository: Centralized file storage
Access Control: Role-based document permissions
Version Management: Document history and versioning
Search and Discovery: Full-text search capabilities

Data Flow Architecture

Hybrid Architecture Pattern

The MyNATCA platform uses a hybrid data access pattern that optimizes performance while maintaining data integrity:

Read Operations:

Discord bot and Hub perform direct Supabase reads for member info, facilities, regions, positions
No API intermediary for read operations
Optimizes performance by reducing network hops
Enables real-time data access with low latency

Write Operations:

All writes go through Platform API endpoints for centralized validation and logging
Discord verification creates verification requests via API
Member updates processed through API
Comprehensive audit logging and business rule enforcement

Benefits:

Faster read operations with direct database access
Centralized write validation and logging
Single source of truth in Supabase
Better performance and data consistency

Primary Data Flow

Authentication Flow

Technology Stack

Database Layer

Supabase (PostgreSQL): Primary application database
- Row Level Security (RLS) policies
- Real-time subscriptions
- Edge functions for integrations
- Automated backups and monitoring
- Multi-schema organization:
  - dev - Development shared tables (members, facilities, regions, positions)
  - discord_dev - Development Discord tables (verification_requests, validation_logs)
  - public - Production shared tables
  - discord - Production Discord tables
- Critical: discord and discord_dev schemas must be exposed in Supabase API settings
MySQL: Legacy source database
- Read-only access for synchronization
- Maintained by external systems
- Source of truth for member data

Application Layer

Node.js: Primary runtime environment
Express.js: Main backend framework and HTTP server
Vue.js: Framework for Member Hub application (port 1301)
Discord.js: Discord API integration
TypeScript: Type safety and development tooling

Authentication & Authorization

Auth0: Identity provider and user management
- OAuth 2.0 / OpenID Connect
- Custom claims for member metadata
- Management API for programmatic access
- Multi-factor authentication support

Infrastructure & Deployment

Digital Ocean App Platform: Multi-service deployment environment
Docker: Containerization with Node.js 18 Alpine base images
PM2: Process management for production environments
Redis: Session storage and caching layer

Security Architecture

Authentication Security

JWT Token Validation: Cryptographic verification of all tokens
Multi-Factor Authentication: Optional MFA via Auth0
Session Management: Secure session handling with expiration
State Management: Anti-CSRF tokens in OAuth flows

Database Security

Row Level Security: Database-level access controls
Service Role Isolation: Dedicated roles for sync operations
Connection Encryption: SSL/TLS for all database connections
Audit Logging: Comprehensive tracking of data access

API Security

Rate Limiting: Protection against abuse
Input Validation: Strict validation of all inputs
CORS Configuration: Controlled cross-origin access
Environment Isolation: Separate configs for environments

Scalability Considerations

Database Scalability

Read Replicas: Distribute read queries across replicas
Connection Pooling: Efficient database connection management
Query Optimization: Indexed queries and performance monitoring
Horizontal Scaling: Supabase handles automatic scaling

Application Scalability

Stateless Design: Applications designed for horizontal scaling
Microservices Architecture: Independent scaling of components
Caching Strategy: Redis for session and data caching
CDN Integration: Static asset distribution

Sync System Scalability

Batch Processing: Configurable batch sizes for performance
Parallel Processing: Independent sync operations
Error Recovery: Resilient to transient failures
Resource Management: Memory and CPU optimization

Development Workflow

Code Organization

mynatca-platform/
├── docs/                    # Comprehensive documentation
├── routes/                  # Express.js API routes
├── middleware/             # Express middleware (proxy, auth)
├── lib/                    # Shared utilities and helpers
├── sync/                   # Data synchronization system
├── supabase/               # Database schema and migrations
├── shared/                 # Shared types and utilities
├── scripts/                # Deployment and utility scripts
├── server.js               # Main Express application
├── Dockerfile              # Production container configuration
└── ecosystem.config.js     # PM2 process management

mynatca-discord/
├── commands/               # Discord slash commands
├── lib/                    # Modular architecture libraries
│   ├── auth0/             # Auth0 integration utilities
│   ├── config.js          # Configuration management
│   ├── eventHandlers.js   # Discord event processing
│   ├── httpServer.js      # Webhook and HTTP server
│   ├── memberValidator.js # Member validation logic
│   ├── roleManager.js     # Discord role management
│   └── webhookHandler.js  # Webhook processing
└── bot.js                  # Main bot entry point (78 lines)

Development Process

Feature Development: Start in platform for infrastructure changes
Integration Testing: Verify compatibility with dependent applications
Documentation Updates: Maintain current documentation
Code Review: Peer review for all changes
Deployment: Staged rollout through environments

This architecture provides a solid foundation for the MyNATCA platform while maintaining flexibility for future growth and evolution.

🔧 Technical Documentation Platform Integration