--- name: enterprise-app-foundation description: A high-performance blueprint for distributed applications requiring dual-persistence, secure identity governance, and fault-tolerant AI orchestration. --- # Enterprise Application Foundation (Technical Deep Dive) This skill provides the architectural substrate for rebuilding industrial-grade distributed systems from a blank slate. ## 🏗️ 1. Infrastructure: Distributed Persistence Nexus Implement a **Dialect-Agnostic Proxy** to support both local development and cluster-scale deployment. ### Persistence Logic Pattern ```typescript interface DatabaseProxy { query: (sql: string, params?: any[]) => Promise; run: (sql: string, params?: any[]) => Promise; get: (sql: string, params?: any[]) => Promise; all: (sql: string, params?: any[]) => Promise; transaction: (fn: () => Promise) => Promise; } \/\/ Dialect Translation Technique const isPostgres = !!process.env.POSTGRES_HOST; const translateParams = (text: string) => { let index = 1; return text.replace(\/\?\/g, () => `$${index++}`); \/\/ Converts ? to $1, $2, etc. }; ``` ### Swarm-Ready Docker Configuration - **Postgres Nexus**: Image `postgres:15-alpine`. - **Sequential Schema Protocol**: Postgres drivers often fail on multi-statement strings. Always `.split(';')` and execute sequentially during `initDb`. - **Relational Integrity**: Use `ON UPDATE CASCADE` for all identity references to allow seamless migration of technician IDs without violating foreign keys. - **Fault-Tolerant Seeding**: Wrap dependent record insertions (Mentorship, User Badges) in diagnostic `try-catch` blocks. This ensures that a single foreign key mismatch does not crash the entire orchestration, allowing the core infrastructure (Courses, Modules, Lessons, Quizzes) to be established. --- ## 🛡️ 2. Security: Identity Governance & Access Resilience Stateless security optimized for multi-node deployments where shared memory is unavailable. ### The "Nuclear Governance" Override Always implement a hard-coded memory override for the project's **Industrial Master** email. This ensures that even if database seeding fails or a technician record is stuck in a legacy "Hold" state, the master can still log in to fix the system. ```typescript \/\/ Pattern in login route if (email.toLowerCase() === 'master@domain.com') { user.status = 'active'; \/\/ In-memory override user.roles = JSON.stringify(['Admin']); } ``` ### Identity Sync Best Practices - **Conflict Strategy**: Always synchronize personnel records based on **Email** (`ON CONFLICT(email)`), as `user_id` can drift between manual signups and automated seeds. - **Priority Seeding**: Always seed the `Users` table (Identity Nexus) BEFORE any dependent tables (Logs, Enrollments) to prevent relational link failures. - **Input Normalization**: Always `.trim()` and `LOWER()` email addresses during both Signup and Login to ensure identity audits are resilient to typo-driven lockouts. --- ## 🛠️ 5. Docker Desktop: Advanced Build & Maintenance (Compiled) This skill optimizes Docker for development environments and eliminates common binary architectural failures. ### The "Zero-Crash" Build Protocol: 1. **Model Portability**: Always replace native `bcrypt` with `bcryptjs`. Native binaries compiled on Windows hosts will crash with `Exec format error` when mounted into Linux containers. 2. **Anonymous Volume Shadowing**: In your `docker-compose.yml`, mount your project root but **shadow** the node_modules folder: ```yaml volumes: - .:\/app - \/app\/node_modules # Forces usage of container-built modules ``` 3. **Bootstrapping Entrypoints**: Use a `docker-entrypoint.sh` to handle automated seeding (`npm run seed`) and environment synchronization on every boot. --- ## 🤖 3. AI: Resilient Multi-Model Orchestration A critical layer for automating complex logic while maintaining enterprise-level uptime. ### The "Industrial Retry" Algorithm Implement a global wrapper for AI SDKs (Google Generative AI, OpenAI, etc.). - **Retries**: 5-7 attempts with exponential backoff. - **Models**: High-performance reasoning via `gemini-3-flash-preview` and visual synthesis via `gemini-3-pro-image-preview`. --- --- --- ## 🌐 6. Docker Swarm: Industrial Orchestration Platform This governs the production-grade deployment across the Tallman multi-node cluster. ### Cluster Infrastructure - **High Availability Nexus**: 3 Manager Nodes (10.10.20.36, .61, .63) orchestrated by **Keepalived** for a Virtual IP (10.10.20.65) failover. - **Shared Persistence**: Centralized NFS storage server (10.10.20.64) mounted at `\/var\/data` on all nodes. All application volumes must reside here for cross-node portability. - **Automated Ingress**: **Traefik** handles routing and SSL (Let's Encrypt) via AWS Route 53 DNS validation. ### Stack Deployment Protocol Always use the standardized **Makefile** at `\/var\/data\/config\/` for registry operations. - `make deploy STACK=`: Initialize\/Update stack. - `make update STACK=`: Force redeploy with latest images. - `make list`: Audit all active industrial stacks. ### Network Isolation Protocol For security compliance, every stack must implement a dual-network architecture: 1. **`_traefik`**: An overlay network for external Traefik routing. 2. **`_internal`**: An overlay network for inter-container communication (e.g., App to DB), isolated from the ingress. --- ## 🛠️ Re-Implementation Workflow 1. **Bootstrap**: Initialize `package.json` with `express`, `pg`, `better-sqlite3`, `jsonwebtoken`, `bcryptjs`. 2. **Persistence**: Build `db.ts` with sequential schema execution and CASCADE support. 3. **Identity**: Create authentication routes with Governance Overrides and Email-First sync logic. 4. **Orchestration**: Define the `docker-compose.yml` (without version tag) using `bullseye-slim`. 5. **Entrypoint**: Create and `chmod +x` a `docker-entrypoint.sh` for runtime bootstrapping. 6. **Production Sync**: Move deployment manifests to `\/var\/data\/config\/` on the Swarm Master and execute `make deploy`. 7. **Documentation Protocol**: Update `README.md` to explicitly state the **Verified Deployment Paths** (Local Developer vs. Industrial Swarm), **Persistence Compliance** standards, the **Master Registry** (the application's specific repository URL), and the **Network Access Points** (IP and Port addresses specific to the application) immediately following the platform introduction.