PowerOn Nyla Frontend

🏗️ Project Architecture

graph TB
    %% Environment Files
    ENV_DEV[".env.dev<br/>Development"]
    ENV_PROD[".env.prod<br/>Production"]
    ENV_INT[".env.int<br/>Integration"]
    
    %% Configuration System
    CONFIG_TS["config.ts<br/>TypeScript Config<br/>(React Frontend)"]
    CONFIG_JS["serverConfig.js<br/>JavaScript Config<br/>(Node.js Servers)"]
    
    %% Source Code
    SRC["src/<br/>React Components"]
    PUBLIC["public/<br/>Static Assets"]
    HTML["index.html<br/>Main Template"]
    
    %% Build Process
    VITE["vite.config.ts<br/>Build Configuration"]
    PACKAGE["package.json<br/>Dependencies & Scripts"]
    TSCONFIG["tsconfig.json<br/>TypeScript Config"]
    
    %% Build Output
    DIST["dist/<br/>Built Application"]
    
    %% Servers
    SERVER_DEV["server.js<br/>Dev Server"]
    SERVER_DEPLOY["deploy-server.js<br/>Deploy Server"]
    SERVER_LEGACY["server.js<br/>Legacy Server"]
    
    %% Deployment
    GITHUB[".github/workflows/<br/>GitHub Actions"]
    AZURE["Azure Static Web Apps"]
    STATIC_CONFIG["staticwebapp.config.json<br/>Azure Config"]
    
    %% Environment Flow
    ENV_DEV --> CONFIG_TS
    ENV_PROD --> CONFIG_TS
    ENV_INT --> CONFIG_TS
    
    ENV_DEV --> CONFIG_JS
    ENV_PROD --> CONFIG_JS
    ENV_INT --> CONFIG_JS
    
    %% Configuration Usage
    CONFIG_TS --> SRC
    CONFIG_JS --> SERVER_DEV
    CONFIG_JS --> SERVER_DEPLOY
    CONFIG_JS --> SERVER_LEGACY
    
    %% Build Process
    SRC --> VITE
    PUBLIC --> VITE
    HTML --> VITE
    PACKAGE --> VITE
    TSCONFIG --> VITE
    CONFIG_TS --> VITE
    
    VITE --> DIST
    
    %% Server Usage
    DIST --> SERVER_DEV
    DIST --> SERVER_DEPLOY
    DIST --> SERVER_LEGACY
    
    %% Deployment Flow
    GITHUB --> ENV_PROD
    GITHUB --> ENV_INT
    GITHUB --> DIST
    GITHUB --> SERVER_DEPLOY
    GITHUB --> AZURE
    
    STATIC_CONFIG --> AZURE
    
    %% Styling
    classDef envFile fill:black,stroke:#01579b,stroke-width:2px
    classDef configFile fill:black,stroke:#4a148c,stroke-width:2px
    classDef sourceFile fill:black,stroke:#1b5e20,stroke-width:2px
    classDef buildFile fill:black,stroke:#e65100,stroke-width:2px
    classDef serverFile fill:black,stroke:#880e4f,stroke-width:2px
    classDef deployFile fill:black,stroke:#33691e,stroke-width:2px
    
    class ENV_DEV,ENV_PROD,ENV_INT envFile
    class CONFIG_TS,CONFIG_JS configFile
    class SRC,PUBLIC,HTML sourceFile
    class VITE,PACKAGE,TSCONFIG,DIST buildFile
    class SERVER_DEV,SERVER_DEPLOY,SERVER_LEGACY serverFile
    class GITHUB,AZURE,STATIC_CONFIG deployFile

Flow Overview:

1. Environment files → Configuration system → Source code
2. Source code → Build process → Built application
3. Built application → Servers → Deployment
4. GitHub Actions → Azure Static Web Apps

🔧 Configuration Setup

The app uses a dual configuration system to handle environment variables across different contexts:

Configuration Files

• config/config.ts - TypeScript config for React frontend

  • Why: Provides type-safe access to environment variables in the browser
  • How: Uses import.meta.env (Vite's environment API) to access VITE_* variables
  • Used by: All React components, hooks, and frontend logic

• config/serverConfig.js - JavaScript config for Node.js servers

  • Why: Node.js can't access import.meta.env, needs process.env
  • How: Uses dotenv to load .env files and process.env to access variables
  • Used by: Express servers and build scripts

Environment Files

• config/.env.dev - Development environment variables

  • Why: Separate config for local development with debug settings
  • How: Copied to root .env by npm run dev command
  • Contains: Local API URLs, debug flags, dev-specific settings

• config/.env.prod - Production environment variables

  • Why: Production-specific settings (live API URLs, optimized settings)
  • How: Copied to root .env by GitHub Actions workflow
  • Contains: Production API URLs, security settings, performance configs

• config/.env.int - Integration environment variables

  • Why: Testing environment that mirrors production but with test data
  • How: Copied to root .env by integration deployment workflow
  • Contains: Staging API URLs, test user credentials, integration settings

Usage

# Development (loads .env.dev)
npm run dev

# Production build (loads .env.prod)
npm run build:prod

# Integration build (loads .env.int)
npm run build:int

🖥️ Server Files

• scripts/server.js - Express server for local development

  • Why: Serves the built React app locally for testing
  • How: Serves static files from dist/ directory on port 3000
  • Used by: Developers running npm run dev or manual testing

• scripts/deploy-server.js - Express server for deployment

  • Why: Production server that serves the built app in cloud environments
  • How: Serves static files and handles routing for SPA (Single Page Application)
  • Used by: Azure Static Web Apps and other deployment platforms

• server.js - Legacy server (kept for compatibility)

  • Why: Backup server file in case deployment scripts need it
  • How: Basic Express server setup
  • Used by: Fallback option for deployments

Both servers use config/serverConfig.js for environment variables and logging.

📁 Root Directory Files

Core Application Files

• package.json - Node.js project configuration

  • Why: Defines dependencies, scripts, and project metadata
  • How: Used by npm/yarn to install packages and run scripts
  • Contains: Dependencies, build scripts, project info

• vite.config.ts - Vite build tool configuration

  • Why: Configures how Vite builds and serves the React app
  • How: Defines plugins, build options, and environment variable handling
  • Contains: React plugin, HTML plugin, environment loading, build settings

• tsconfig.json - TypeScript compiler configuration

  • Why: Defines TypeScript compilation rules and target settings
  • How: Used by TypeScript compiler and IDE for type checking
  • Contains: Compiler options, file includes/excludes, module resolution

• index.html - Main HTML template

  • Why: Entry point for the React application
  • How: Vite injects the built JavaScript and CSS into this template
  • Contains: HTML structure, dynamic title injection, script tags

Build and Deployment

• staticwebapp.config.json - Azure Static Web Apps configuration
  • Why: Configures routing and MIME types for Azure deployment
  • How: Used by Azure Static Web Apps service
  • Contains: Navigation fallback rules, MIME type mappings

Source Code and Assets

• src/ - Source code directory

  • Why: Contains all React components, hooks, and application logic
  • How: Vite processes these files during build
  • Contains: Components, pages, hooks, contexts, locales, assets

• public/ - Static assets

  • Why: Files that should be copied directly to build output
  • How: Vite copies these files to dist/ during build
  • Contains: Images, logos, favicons, other static files

Configuration and Scripts

• config/ - Configuration files directory

  • Why: Centralizes all configuration and environment files
  • How: Contains environment files and config modules
  • Contains: Environment files, config.ts, serverConfig.js

• scripts/ - Server scripts directory

  • Why: Separates server-related files from main application code
  • How: Contains Express server implementations
  • Contains: server.js, deploy-server.js

CI/CD

• .github/workflows/ - GitHub Actions workflows
  • Why: Automates deployment to different environments
  • How: Triggers on git pushes and deploys to Azure
  • Contains: YAML files for dev, int, and prod deployments