frontend_nyla/README.md

# PowerOn Nyla Frontend

## 🏗️ Project Architecture

```mermaid
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
```bash
# 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