Local development server

Running the Flask backend locally and the CLI helpers for extracting or validating contacts without the Electron shell.

• Flask development server configuration with debug mode, host binding, and port settings
• CLI functions for local testing and development workflows
• Development environment setup, including dependency installation and server startup procedures
• Examples of local API testing, development workflow integration, and debugging techniques
• The relationship between local development server and production deployment
• Common development issues, environment variable configuration, and performance considerations for local testing

The project includes two local development servers and a set of Python utilities:

• A Flask-based local development server for user management and file upload workflows
• A separate Flask-based Python backend service for contact processing and validation
• Electron main process that launches a React/Vite dev server and integrates with the Python backend
• Python utilities for contact extraction, manual number parsing, and phone number validation

graph TB
subgraph "Electron Dev Server"
EMain["electron/src/electron/main.js"]
EUtils["electron/src/electron/utils.js"]
EPkg["electron/package.json"]
end
subgraph "Local Dev Server"
LApp["localhost/app.py"]
end
subgraph "Python Backend"
PApp["python-backend/app.py"]
PReq["python-backend/requirements.txt"]
PExtract["python-backend/extract_contacts.py"]
PParse["python-backend/parse_manual_numbers.py"]
PValidate["python-backend/validate_number.py"]
end
EMain --> EPkg
EMain --> EUtils
EMain --> LApp
EMain --> PApp
PApp --> PReq
PApp --> PExtract
PApp --> PParse
PApp --> PValidate

• Local Flask development server (localhost/app.py): Provides HTML forms and JSON APIs for user registration/login, dynamic table creation, and file upload handling. It runs with debug mode enabled.
• Python backend Flask service (python-backend/app.py): Offers health checks, file upload processing, contact extraction from CSV/Excel/TXT, manual number parsing, and phone number validation. It binds to host 0.0.0.0 and port 5034.
• Electron main process (electron/src/electron/main.js): Launches the React/Vite dev server at http://localhost:5173 in development mode and loads the Electron window accordingly.
• Python utilities: Standalone scripts for extracting contacts, parsing manual numbers, and validating phone numbers.

Key configuration highlights:

• Local dev server: debug=True, default host/port unspecified (Flask defaults)
• Python backend: debug=True, host=“0.0.0.0”, port=5034
• Electron dev server: Vite dev server at http://localhost:5173

The local development architecture integrates Electron, a React/Vite dev server, and two Flask services:

• Electron main process detects development mode and loads the React dev server URL
• The local Flask server handles user and file operations for the legacy UI
• The Python backend Flask service exposes REST endpoints for contact processing and validation
• Python utilities can be invoked directly for offline testing

sequenceDiagram
participant User as "Developer"
participant Electron as "Electron Main"
participant React as "Vite Dev Server"
participant Local as "Local Flask Server"
participant Backend as "Python Backend Flask"
User->>Electron : Start Electron dev
Electron->>Electron : isDev() -> development
Electron->>React : Load http : //localhost : 5173
React-->>Electron : Dev server ready
Electron->>Local : Serve legacy UI routes
Electron->>Backend : Call /health and processing endpoints
Backend-->>Electron : JSON responses
Local-->>Electron : HTML/JSON responses

Local flask development server (localhost/app.py)#

• Purpose: Legacy UI and file upload workflows with user management and dynamic table creation
• Flask configuration:
• Debug mode enabled
• SQLite database configured
• CORS enabled for all routes
• Routes:
• HTML forms for login/signup and file upload
• JSON APIs for login/signup, table loading, file upload, and table selection
• Data model: User table with JSON field for dynamic tables
• File upload handling: Validates allowed extensions and saves uploads

flowchart TD
Start(["Request to /"]) --> Method{"HTTP Method"}
Method --> |GET| RenderLogin["Render login template"]
Method --> |POST| Validate["Validate credentials"]
Validate --> Valid{"Valid?"}
Valid --> |Yes| RenderButtons["Render buttons.html with user tables"]
Valid --> |No| RenderError["Render index.html with error"]
RenderButtons --> End(["Response"])
RenderError --> End

Python backend flask service (python-backend/app.py)#

• Purpose: REST API for contact processing and validation
• Flask configuration:
• Debug mode enabled
• Host bound to 0.0.0.0
• Port set to 5034
• Upload folder configured with allowed file types and size limit
• Endpoints:
• GET /health: Health check
• POST /upload: Upload and process CSV/Excel/TXT files
• POST /parse-manual-numbers: Parse manual number entries
• POST /validate-number: Validate a single phone number
• Utilities:
• Phone number cleaning and normalization
• Contact extraction from multiple file formats
• Error handling and cleanup

sequenceDiagram
participant Client as "Client"
participant Backend as "Python Backend"
participant FS as "Filesystem"
Client->>Backend : POST /upload {multipart/form-data}
Backend->>FS : Save file to uploads/
Backend->>Backend : Detect file type and extract contacts
Backend->>FS : Remove uploaded file
Backend-->>Client : JSON {success, contacts, count}

Electron development server integration#

• Development mode detection via environment variable
• Loads React/Vite dev server at http://localhost:5173
• Enables DevTools in development
• Integrates with both local Flask and Python backend services

sequenceDiagram
participant Electron as "Electron Main"
participant Utils as "utils.js"
participant Vite as "Vite Dev Server"
Electron->>Utils : isDev()
Utils-->>Electron : true/false
Electron->>Vite : loadURL("http : //localhost : 5173")
Vite-->>Electron : Ready

Python utilities (CLI functions)#

• Purpose: Standalone CLI utilities for contact processing and validation
• Functions:
• Contact extraction from CSV/Excel/TXT
• Manual number parsing with name/number detection
• Phone number validation and normalization
• Usage: Run as Python scripts with file arguments or stdin/stdout

flowchart TD
Start(["CLI Entry"]) --> ArgCheck{"File provided?"}
ArgCheck --> |No| PrintError["Print error and exit"]
ArgCheck --> |Yes| ExtCheck{"Extension?"}
ExtCheck --> |csv| ExtractCSV["Extract contacts from CSV"]
ExtCheck --> |txt| ExtractTXT["Extract contacts from TXT"]
ExtCheck --> |xlsx/xls| ExtractXLSX["Extract contacts from Excel"]
ExtCheck --> |Other| Unsupported["Unsupported file type"]
ExtractCSV --> Output["Print JSON contacts"]
ExtractTXT --> Output
ExtractXLSX --> Output
Unsupported --> Exit(["Exit"])
Output --> Exit
PrintError --> Exit

• Local Flask server depends on:
• Flask, SQLAlchemy, Flask-CORS, Werkzeug
• Python backend depends on:
• Flask, Flask-CORS, pandas, openpyxl, xlrd, werkzeug
• Electron dev server depends on:
• Vite, concurrently, wait-on, electron, react, react-dom

graph LR
LApp["localhost/app.py"] --> Flask["Flask"]
LApp --> SQLAlchemy["SQLAlchemy"]
LApp --> CORS["Flask-CORS"]
PApp["python-backend/app.py"] --> Flask
PApp --> Pandas["pandas"]
PApp --> Openpyxl["openpyxl"]
PApp --> Xlrd["xlrd"]
PApp --> Werkzeug["Werkzeug"]
EMain["electron/src/electron/main.js"] --> Vite["Vite"]
EMain --> Electron["Electron"]
EMain --> React["React"]

• Local Flask server:
• Uses SQLite in-memory-like persistence; suitable for development
• File uploads saved to filesystem; ensure adequate disk space
• Debug mode enabled; avoid enabling in production
• Python backend:
• Max upload size limited to 16 MB
• File processing performed synchronously; consider async for heavy loads
• Phone number cleaning and validation are CPU-bound; batch processing recommended
• Electron dev server:
• Vite hot reload improves iteration speed
• Puppeteer headless mode reduces overhead for WhatsApp integration

Common development issues and resolutions:

• Local Flask server not starting:
• Ensure Python dependencies are installed
• Confirm debug mode is enabled and host/port defaults are acceptable
• Python backend not reachable:
• Verify host binding to 0.0.0.0 and port 5034
• Check firewall and network configuration
• Electron dev server failing to load:
• Confirm Vite dev server is running at http://localhost:5173
• Ensure NODE_ENV is set to development
• File upload errors:
• Validate allowed file types and sizes
• Check upload directory permissions
• Phone number validation failures:
• Ensure numbers meet length and format requirements
• Use the validation endpoint to diagnose issues

Run Flask alone when debugging parsers. It is faster than relaunching Electron for every fixture file.

Development environment setup#

• Install Electron dependencies:
• Navigate to electron directory and run npm install
• Install Python backend dependencies:
• Navigate to python-backend directory and run pip install -r requirements.txt
• Start development server:
• From electron directory, run npm run dev to launch both React/Vite and Electron

Local API testing examples#

• Health check:
• GET http://localhost:5034/health
• Upload and process contacts:
• POST http://localhost:5034/upload with multipart/form-data
• Parse manual numbers:
• POST http://localhost:5034/parse-manual-numbers with JSON payload
• Validate phone number:
• POST http://localhost:5034/validate-number with JSON payload

Relationship between local development and production deployment#

• Local development:
• Electron dev server loads Vite dev server at http://localhost:5173
• Local Flask server runs with debug mode enabled
• Python backend runs with debug mode and binds to 0.0.0.0:5034
• Production deployment:
• Electron builds static assets and runs packaged app
• Python backend can be deployed behind a reverse proxy or containerized
• Local Flask server is intended for development and should not be used in production

Environment variable configuration#

• Electron development:
• NODE_ENV=development enables dev server loading
• Python backend:
• No explicit environment variables required; configure host/port in app.run()