TeleSec/.github/copilot-instructions.md

TeleSec - Secure Distributed Communication Application

TeleSec is a Spanish Progressive Web Application (PWA) built with vanilla JavaScript, HTML, and CSS that provides secure group communication using a local-first PouchDB datastore with optional CouchDB replication for syncing. The application allows users to join encrypted communication groups using group codes and secret keys.

ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Working Effectively

Build and Deploy Process

• Build the application (FASTEST BUILD EVER - 0.036 seconds):
  • cd /home/runner/work/TeleSec/TeleSec
  • python3 build.py
  • NEVER CANCEL: Build completes in under 0.1 seconds. No timeout needed.
  • The build script copies files from assets/ to dist/ and processes template variables in src/ files.

Serving the Application

• Python HTTP Server (Recommended for development):

  • cd /home/runner/work/TeleSec/TeleSec/dist
  • python3 -m http.server 8000
  • Access at: http://localhost:8000

• Node.js HTTP Server (Alternative with CORS support):

  • cd /home/runner/work/TeleSec/TeleSec/dist
  • npx http-server . --port 8001 --cors
  • NEVER CANCEL: First run takes ~14 seconds to download http-server package. Set timeout to 30+ seconds.
  • Access at: http://localhost:8001

Development Environment Requirements

• Python 3.x (for build script) - Version 3.12.3+ confirmed working
• Node.js and npm (optional, for alternative serving) - Version 20.19.4+ confirmed working
• Web browser (for testing the PWA functionality)

Validation and Testing

Mandatory Validation Steps

1. Build Validation:

   • Run python3 build.py and verify it completes in under 1 second
   • Verify dist/ directory is created with all assets and processed files
   • Check that template variables (%%PREFETCH%%, %%VERSIONCO%%, %%ASSETSJSON%%) are replaced

2. Application Functionality Test:

   • Start web server: python3 -m http.server 8000 in dist/ directory
   • Navigate to http://localhost:8000 in browser
   • CRITICAL LOGIN TEST: Enter any group code (e.g., "TEST") and secret key (e.g., "SECRET123")
   • Click "Iniciar sesión" button
   • VERIFY NETWORK CONNECTIVITY: Confirm the header shows connected nodes (e.g., "TeleSec - TEST - (8 nodos)")
   • SUCCESS INDICATORS:
     • Application loads without errors
     • Login form accepts credentials
     • Distributed network connects (node count > 0)
     • No JavaScript console errors except expected WebSocket connection failures

3. PWA Features Test:

   • Verify Service Worker registration in browser console
   • Check manifest.json loads correctly
   • Confirm offline caching functionality

Error Handling Validation

• Build Script Errors: Python syntax errors will cause build to fail with clear error messages
• Network Connectivity: Some WebSocket connections to gun-manhattan.herokuapp.com may fail - this is expected
• Browser Compatibility: Application works in modern browsers supporting Service Workers

Repository Structure

Key Files and Directories

/home/runner/work/TeleSec/TeleSec/
├── build.py                    # Main build script - processes template variables
├── index.html                  # Build error fallback (should never be served)
├── README.md                   # Basic repository information (minimal)
├── LICENSE                     # Project license
├── CNAME                       # GitHub Pages configuration
├── .gitignore                  # Excludes dist/, radata/, node_modules/
├── src/                        # Source files with template variables
│   ├── index.html             # Main application HTML with %%PREFETCH%% variables
│   ├── app_logic.js           # Core application logic and authentication
│   ├── app_modules.js         # Application modules and utilities
│   ├── config.js              # Configuration and CouchDB setup
│   ├── db.js                  # PouchDB wrapper and replication
│   ├── pwa.js                 # Progressive Web App functionality
│   ├── sw.js                  # Service Worker with cache configuration
│   └── page/                  # Individual page modules
│       ├── login.js           # Login functionality
│       ├── index.js           # Main dashboard
│       ├── materiales.js      # Materials management
│       ├── personas.js        # People management
│       ├── supercafe.js       # SuperCafé module
│       ├── comedor.js         # Dining hall module
│       ├── importar.js        # Data import functionality
│       ├── exportar.js        # Data export functionality
│       ├── resumen_diario.js  # Daily summary
│       └── notificaciones.js  # Notifications
└── assets/                     # Static assets copied to dist/
    ├── manifest.json          # PWA manifest
    ├── *.png, *.jpg           # Icons and images
    ├── static/                # JavaScript libraries and CSS
│   │   ├── pouchdb (via CDN)  # PouchDB is used for local storage and replication
    │   ├── webrtc.js          # WebRTC functionality
    │   ├── euskaditech-css/   # CSS framework
    │   └── ico/               # Application icons
    └── page/                   # Page-specific assets (empty placeholder)

Build Process Details

The build.py script performs these operations:

1. Clean: Removes existing dist/ directory (if it exists)
2. Copy Assets: Copies all files from assets/ to dist/
3. Process Templates: Processes files from src/ and replaces:
   • %%PREFETCH%% - Generates link prefetch tags for all assets
   • %%VERSIONCO%% - Inserts version code "2025-08-04_1"
   • %%ASSETSJSON%% - Inserts JSON array of all asset files
4. Output: Creates complete deployable application in dist/

Application Architecture

Technology Stack

• Frontend: Vanilla JavaScript, HTML5, CSS3
• Data Layer: PouchDB (local-first) with optional CouchDB replication
• Networking: WebRTC for peer-to-peer connections (where applicable)
• Authentication: Group codes + secret keys (converted to uppercase)
• Storage: Browser LocalStorage + PouchDB local datastore
• PWA Features: Service Worker, Web App Manifest

Remote Sync (Optional)

The application can optionally replicate to a remote CouchDB server for cloud backup and multi-device syncing. Configure the CouchDB server, database name, and credentials in the login/setup form in the application.

Application Modules

• Login/Authentication: Group-based access with secret keys
• Materials Management: Track and manage materials/supplies
• People Management: Manage group members
• SuperCafé: Café/beverage ordering system
• Dining Hall: Restaurant/meal management
• Import/Export: Data backup and restoration
• Daily Summary: Reports and analytics
• Notifications: Alert system

Common Development Tasks

Making Changes to the Application

1. ALWAYS edit files in src/ directory, never dist/
2. Run python3 build.py to rebuild after changes
3. Refresh browser or restart web server to see changes
4. Test authentication flow and network connectivity after any changes

Adding New Features

1. Create new JavaScript files in src/page/ for new modules
2. Add script references in src/index.html
3. Update assets if new static files are needed
4. Rebuild and test complete user workflows

Debugging Common Issues

• Login Issues: Check browser console for replication/auth errors and DB initialization logs
• Network Connectivity: Verify remote CouchDB server is reachable and replication is active
• Build Issues: Check Python syntax in build.py
• Performance: Monitor browser DevTools Network tab for asset loading

Validation Scenarios

Complete User Workflow Test

After making any changes, ALWAYS test this complete scenario:

1. Build and Serve:

   cd /home/runner/work/TeleSec/TeleSec
   python3 build.py
   cd dist
   python3 -m http.server 8000
   

2. Login Test:

   • Navigate to http://localhost:8000
   • Enter group code: "TEST"
   • Enter secret key: "SECRET123"
   • Click "Iniciar sesión"
   • Verify header shows: "TeleSec - TEST" and that the login is accepted

3. Network Connectivity Test:

   • Confirm green connection indicator appears (bottom right)

• Check browser console shows PouchDB replication logs when a remote is configured
• Verify heartbeat/last-seen docs are being updated in the local DB

4. PWA Functionality Test:
   • Check Service Worker registers successfully
   • Verify offline caching works (Network tab → Offline)
   • Test manifest.json loads correctly

Quick Reference Commands

Essential Operations

# Build application (< 0.1 seconds)
python3 build.py

# Serve with Python (most compatible)
cd dist && python3 -m http.server 8000

# Serve with Node.js (advanced features)
cd dist && npx http-server . --port 8001 --cors

# Clean rebuild
rm -rf dist && python3 build.py

# Check build output
ls -la dist/

File Structure Verification

# Verify all source files exist
find src/ -name "*.js" -o -name "*.html" | sort

# Check template variable processing
grep -r "%%.*%%" dist/ || echo "All template variables processed correctly"

# Verify assets copied correctly
diff -r assets/ dist/ --exclude="*.js" --exclude="*.html" || echo "Some differences expected due to processing"

CRITICAL REMINDERS:

• NEVER CANCEL: Builds complete in under 0.1 seconds - no timeout needed
• ALWAYS test login and network connectivity after changes
• Edit source files in src/ directory only, never dist/
• Test with real user credentials to verify distributed networking
• Monitor browser console for connection status and errors