Skip to content

First Principles - Development Guidelines

Core Philosophy

These are our fundamental principles to keep development simple, efficient, and maintainable. When in doubt, refer back to these principles.

🔑 SSH & Server Access

PRINCIPLE: One Key for All Servers

  • ✅ USE: Single SSH key (es7_production_key) for all our servers
  • ❌ AVOID: Creating separate keys for each server - leads to confusion and mixed setups
  • 📝 RATIONALE: Small team, shared responsibility, simplicity over security complexity

Exception: Keep directsponsor_key separate as it's a different hosting provider.

🌐 User Experience First

PRINCIPLE: Optimize for Bad Connections

  • ✅ USE: Static HTML/CSS/vanilla JS whenever possible
  • ✅ USE: Minimal external dependencies
  • ✅ USE: Small file sizes and efficient loading
  • ❌ AVOID: Heavy frameworks, large JavaScript bundles
  • ❌ AVOID: Unnecessary API calls or real-time features
  • 📝 RATIONALE: Our users often have slow, expensive mobile connections

🏗️ Architecture Simplicity

PRINCIPLE: Separate Concerns, Simple Structure

  • ✅ USE: PHP for server-side logic (simple, widely supported)
  • ✅ USE: Static file serving when possible
  • ✅ USE: Clear separation between auth, data, and presentation
  • ❌ AVOID: Node.js unless absolutely necessary
  • ❌ AVOID: Complex build processes or bundlers
  • ❌ AVOID: Mixing concerns in single applications
  • 📝 RATIONALE: Simple tech stack = easier maintenance, faster loading, fewer dependencies

📁 Project Structure

PRINCIPLE: Consistent, Predictable Layout

project/
├── deploy.sh           # Single deployment script
├── README.md          # Clear setup instructions  
├── src/               # Main application code
├── static/            # CSS, JS, images
└── config/            # Configuration files

🚀 Deployment

PRINCIPLE: Simple, Automated Deployment

  • ✅ USE: Single deploy.sh script per project
  • ✅ USE: Automatic git commits with timestamps
  • ✅ USE: Backup creation before deployment
  • ✅ USE: Health checks after deployment
  • ❌ AVOID: Manual file transfers
  • ❌ AVOID: Complex CI/CD pipelines (for now)

🔄 Git & Version Control

PRINCIPLE: Single Source of Truth

  • ✅ USE: Primary git server with automatic backups
  • ✅ USE: Clear commit messages with project context
  • ✅ USE: Deploy scripts that auto-commit changes
  • ❌ AVOID: Multiple conflicting git repositories
  • ❌ AVOID: Manual version management

🎯 Decision Framework

When making technical decisions, ask:

  1. Does this serve users with bad connections?
  2. Is this the simplest solution that works?
  3. Can someone else easily understand and maintain this?
  4. Does this create unnecessary complexity?

If the answer to #1-3 is "yes" and #4 is "no", proceed. Otherwise, reconsider.

🚨 Warning Signs

Watch out for these complexity creep indicators:

  • Creating new SSH keys for new servers
  • Adding Node.js "just for this one thing"
  • Building features that require real-time updates
  • Adding frameworks for simple interactions
  • Creating multiple git repositories for related projects
  • Manual deployment processes

📋 Infrastructure Documentation

PRINCIPLE: Always Know What's Where

  • ✅ MANDATORY: Update Server Overview after ANY server changes
  • ✅ MANDATORY: Document each server's purpose, services, and access methods
  • ✅ MANDATORY: Keep SSH config and server documentation in sync
  • ❌ NEVER: Make changes without updating documentation
  • 📝 RATIONALE: Lost track = SSH issues, service confusion, potential data loss

The ES2/UselessCoin confusion taught us: Undocumented infrastructure leads to chaos.

Remember: Complexity is the enemy of reliability. When in doubt, choose the simpler path.