# apratham/electron-oauth-app architecture

> Architecture diagram of the GitHub repository apratham/electron-oauth-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apratham/electron-oauth-app
- Repository: https://github.com/apratham/electron-oauth-app

## Overview

##### Project type and purpose
- This is a cross-platform desktop application built with Electron, serving as a reference implementation for OAuth 2.0 (Google and Microsoft) in a desktop environment. It provides login, logout, and splash flows all within a single packaged app.

##### File structure
- Top-level entrypoints:
- main.js – Electron “main” process (app lifecycle, BrowserWindow creation, deep-link handling)
- index.js – Electron “renderer” entrypoint for the primary UI (loaded in index.html)
- Renderer assets (HTML/CSS/JS sets for each screen):
- splash.html/css/js
- login.html/css/js
- logout.html/css/js
- index.html/css/js (post-login UI)
- Shared assets & configuration:
- config/.versionrc, scripts/increment-version.js – version bump tooling
- secrets-example.js – placeholder for OAuth client IDs/secrets (renamed to secrets.js at runtime)
- Packaging & build:
- package.json – dependencies (Electron, electron-builder, Ionic, etc.) and scripts (start, build)
- electron-builder config in package.json (targeting Windows, macOS, Linux)
- CI/CD: GitHub Actions workflow badge in README indicates automated releases via .github/workflows/release.yml

##### Review README insights
- Purpose: showcase Google and Microsoft OAuth flows in an Electron context
- Tech stack: Node.js LTS, Electron ^30.1.1, electron-builder ^24.13.3, Ionic components for UI consistency
- External dependencies: Google OAuth 2.0 endpoints, Microsoft identity platform (Graph API for basic profile scopes)

##### Main components
a. Electron Main Process
- App initialization & window management
- Deep-link / custom URI schema handler (“myapp://auth”) for OAuth callbacks
- IPC channel to/from Renderer processes
- Version bump script integration (calls increment-version.js)
b. Electron Renderer Processes (UI Layer)
- Splash Screen
- Login Screen – triggers OAuth popup via Main Process
- Primary App UI (index.html/js) – displays user info after successful login
- Logout Screen – clears session and returns to login
c. Configuration & Secrets
- secrets.js (client IDs, secrets, redirect URIs) loaded by Main Process
d. External Services
- Google OAuth 2.0 Authorization Server
- Microsoft Identity Platform (Graph API endpoints)
e. Build & Release Pipeline
- electron-builder (packaging to .exe, .dmg, .AppImage)
- GitHub Actions for automated releases

##### Relationships & data flows
- App Startup: Main → launches Splash Renderer
- Renderer → Main via IPC: “ready” event → Main opens Login Renderer
- Login Renderer → Main: “start-oauth” with provider choice → Main opens external OAuth window
- OAuth Window → External Provider (HTTPS request/redirect flow) → Redirect to custom URI → Main intercepts callback
- Main → extracts tokens → IPC send “oauth-success” + token payload → Primary Renderer
- Primary Renderer → calls Main for any further interactions (refresh, logout)
- Logout Renderer → Main clears token state → returns to Login Renderer

##### Architectural patterns & design principles
- Electron’s multi‐process architecture (separation of concerns between Main and Renderer)
- Event‐driven communications via IPC channels
- Externalizing secrets/config to a dedicated file for environment-specific overrides
- Build‐time versioning with a script and configuration file

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        Main["Electron Main Process"]:::coreProc
        ConfigV[".versionrc"]:::configDoc
        IncScript["increment-version.js"]:::configDoc
        Secrets["secrets-example.js"]:::configDoc
    end

    %% UI Layer
    subgraph "UI Layer"
        Splash["Splash Screen"]:::renderer
        Login["Login Screen"]:::renderer
        PrimaryUI["Primary App UI"]:::renderer
        Logout["Logout Screen"]:::renderer
    end

    %% External Services
    subgraph "External Layer"
        GoogleOAuth["Google OAuth 2.0"]:::external
        MicrosoftOAuth["Microsoft Identity Platform"]:::external
    end

    %% CI/CD Layer
    subgraph "CI/CD & Build"
        Builder["electron-builder"]:::buildTool
        Actions["GitHub Actions"]:::buildTool
        PackageJSON["package.json"]:::configDoc
    end

    %% Global Assets
    GlobalStyles["global.css"]:::configDoc
    Assets["assets/"]:::configDoc

    %% Relationships
    Main -->|"launches"| Splash
    Splash -->|"ipc-ready"| Main
    Main -->|"opens"| Login
    Login -->|"ipc-startOauth"| Main
    Main -->|"HTTPS OAuth request"| GoogleOAuth
    Main -->|"HTTPS OAuth request"| MicrosoftOAuth
    GoogleOAuth -->|"redirect myapp://auth"| Main
    MicrosoftOAuth -->|"redirect myapp://auth"| Main
    Main -->|"ipc-oauthSuccess"| PrimaryUI
    PrimaryUI -->|"ipc-logout"| Main
    Main -->|"open logout"| Logout
    Logout -->|"ipc-logoutConfirmed"| Main
    Main -->|"opens"| Login

    %% Build & Release Flow
    PackageJSON -->|"configures"| Builder
    Builder -->|"packages"| Actions

    %% Click Events
    click Main "https://github.com/apratham/electron-oauth-app/blob/main/main.js"
    click Splash "https://github.com/apratham/electron-oauth-app/blob/main/splash.html"
    click Login "https://github.com/apratham/electron-oauth-app/blob/main/login.html"
    click PrimaryUI "https://github.com/apratham/electron-oauth-app/blob/main/index.html"
    click Logout "https://github.com/apratham/electron-oauth-app/blob/main/logout.html"
    click GlobalStyles "https://github.com/apratham/electron-oauth-app/blob/main/global.css"
    click Assets "https://github.com/apratham/electron-oauth-app/tree/main/assets/"
    click ConfigV "https://github.com/apratham/electron-oauth-app/blob/main/config/.versionrc"
    click IncScript "https://github.com/apratham/electron-oauth-app/blob/main/scripts/increment-version.js"
    click Secrets "https://github.com/apratham/electron-oauth-app/blob/main/secrets-example.js"
    click PackageJSON "https://github.com/apratham/electron-oauth-app/blob/main/package.json"

    %% Styles
    classDef coreProc fill:#add8e6,stroke:#000,stroke-width:1px
    classDef renderer fill:#b3d9ff,stroke:#000,stroke-width:1px
    classDef external fill:#a0e6a0,stroke:#000,stroke-width:1px
    classDef configDoc fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef buildTool fill:#f4a460,stroke:#000,stroke-width:1px
```
