Skip to main content

User Interface Overview

This document provides a comprehensive overview of the PermitProof web application user experience, navigation flows, and key UI elements.

Application Architecture​

The PermitProof web application is built with Angular Material 3 and provides a modern, responsive interface for architectural plan review and building code compliance analysis.

Key Technologies:

Landing Page Experience​

Initial Load​

When users first visit the application (/), they experience:

  1. Authentication Check: The app automatically checks Firebase authentication status
  2. Loading State: Shows "Loading your projects..." with a Material Design spinner
  3. Auto-Routing: Once authenticated, users are automatically routed to:
    • Their most recently accessed project, OR
    • A project selection dialog if they have multiple projects

Error States​

The landing page handles several error scenarios:

  • Unauthorized: User not in the access control list → Redirects to /no-access
  • Server Error: Backend connectivity issues → Shows error message with retry button
  • Development Mode: Mock user without permissions → Shows helpful development message

Top App Bar​

The top app bar is present on all pages and provides consistent navigation and user controls.

Common Elements (All Pages)​

  1. CodeProof Logo (left side)

    • Clickable, always returns to landing page
    • Consistent branding across all views

  2. Account Balance Display (right side)

    • Shows current account balance (e.g., "$300.00")
    • Clickable, navigates to billing page
    • Icon: account_balance_wallet

  3. User Profile Menu (far right)

    • User avatar (photo or default icon)
    • Dropdown menu with:
      • User name and email
      • "Billing & Account" option
      • "Admin Console" (only for users with admin role)
      • "Sign Out" option

Project-Specific Elements​

When viewing a project, the top app bar adds:

  1. Hamburger Menu (left of logo)

    • Toggles the left navigation drawer
    • Shows/hides table of contents

  2. Project Title (center-left)

    • Displays current project name
    • Two-line layout: title on top, menu bar below

  3. Menu Bar (below project title)

    • Project Menu:
      • New - Create new project
      • Open - Open existing project
      • Share - Share with other users
      • Make a copy - Duplicate project
      • Delete Project - Remove project (with safety confirmations)
      • Settings - Project configuration
    • View Menu:
      • Tasks - View background task status

  4. Share Button (right side, before balance)

    • Quick access to share dialog
    • Icon: person_add

  5. Task Counter Badge (right side, before balance)

    • Shows number of active background tasks
    • Clickable, navigates to tasks page
    • Updates in real-time

Creating a New Project (End-to-End Journey)​

Step 1: Initiate Project Creation​

Users can create a new project from multiple entry points:

Option A: From Landing Page

  • Click "Create New Project" button (if no projects exist)

Option B: From Project Menu

  • Click Project → New in the menu bar

Option C: From Project Selection Dialog

  • Click "Create New Project" button in the dialog

Step 2: New Project Dialog​

The "Create New Project" dialog appears with the following fields:

  1. PDF File Selection (required)

    • Click to select file or drag-and-drop
    • Shows file name and size (in MB)
    • Only accepts .pdf files
    • Can remove and reselect file

  2. Project ID (required)

    • Text input for unique project identifier
    • Used for project URL and storage
    • Hint: "This will be used to identify your project"

  3. Pages Selection (required)

    • Dropdown with two options:
      • All Pages - Process entire PDF
      • Custom Pages - Select specific pages

  4. Page Numbers (if Custom Pages selected)

    • Text input for page ranges
    • Format: 1,2,3,5-7,10 (comma-separated or ranges)
    • Validated with regex pattern
    • Hint: "Enter comma-separated page numbers or ranges"

Step 3: Project Creation Process​

When user clicks "Create Project":

  1. Validation: Checks all required fields are filled correctly
  2. Project Creation: Creates project via gRPC call
  3. File Upload: Uploads PDF to Google Cloud Storage
  4. Page Ingestion: Starts async task to process selected pages
  5. Navigation: Automatically navigates to new project
  6. Background Processing: Pages are ingested in the background
  7. Task Monitoring: User can view progress in Tasks page

Step 4: Arrival at Project View​

User lands on the project page with:

  • Left drawer showing table of contents (initially empty until pages are ingested)
  • Main viewport with 3 default tabs: Overview, Preview, Compliance
  • Top app bar with project menu and actions

Project View UI Elements​

Left Navigation Drawer (Table of Contents)​

The left drawer displays the project's page structure:

Header:

  • Title: "Table of Contents"
  • Progress bar (shown while loading)

Page List:

  • Each page shows:
    • Page Number - Numeric identifier
    • Page Title - Extracted from PDF or auto-generated
    • Sheet ID - Material chip showing page identifier (if available)
    • Checkbox - For multi-page selection
  • Active Page: Highlighted with distinct styling
  • Checked Pages: Visual indicator for selected pages
  • Empty State: "No pages ingested" message if no pages processed yet

Selected Pages Toolbar (floating):

  • Appears when one or more pages are checked
  • Shows count of selected pages
  • Provides bulk actions:
    • Run code applicability analysis
    • Generate compliance reports
    • Other batch operations

Interaction:

  • Click page to navigate to that page
  • Check/uncheck for multi-selection
  • Drawer can be toggled via hamburger menu

Main Viewport Tabs​

The main viewport uses Material Tabs with 3 default tabs plus dynamic tabs:

Tab 1: Overview​

Purpose: High-level project information and quick actions

Content:

  • Project metadata summary
  • Quick statistics (pages ingested, analyses run, etc.)
  • Recent activity
  • Quick action buttons

Tab 2: Preview​

Purpose: PDF page preview and visual inspection

Content:

  • PDF page rendering using PDF.js
  • Zoom controls
  • Page navigation
  • Annotation tools (if implemented)
  • Side-by-side view options

Tab 3: Compliance​

Purpose: Code applicability analysis and compliance checking

Content:

  • Building code selection
  • Code section browser
  • Applicability analysis results
  • Compliance status indicators
  • Section-specific analysis

Features:

  • Expandable code sections
  • Filtering and search
  • Section selection for detailed analysis
  • Rationale dialogs for AI decisions

Dynamic Tabs (4+)​

Additional tabs can be opened dynamically:

  • Compliance Report Tabs: Generated compliance reports for specific pages
  • Code Section Details: Deep-dive into specific building code sections
  • Custom Analysis Views: User-initiated analysis results

Tab Behavior:

  • First 3 tabs are permanent (cannot be closed)
  • Dynamic tabs (4+) have close buttons
  • Tabs persist during navigation within project
  • Active tab is highlighted

Special Views (Replace Tabs)​

Project Settings View​

Accessed via Project → Settings or clicking "Project Settings" in the left drawer, this view uses a tabbed interface:

Navigation:

  • URL: /projects/:projectId/settings/overview or /settings/files
  • Drawer stays open (smooth SPA navigation - Issue #243)
  • Two tabs: Overview and Files

Overview Tab (/settings/overview):

  1. Legacy Project Banner (Issue #227)

    • Shows for projects without project-metadata.json
    • "Set Up Metadata" button opens creation dialog
    • Dismissible but reappears until metadata created

  2. Project Information Card (Issue #227 - Editable Metadata)

    • Project ID (read-only)
    • Project Name (editable inline)
    • Description (editable inline multi-line)
    • Address (editable inline with Google Places autocomplete - Issue #236)
      • Street address field with autocomplete suggestions
      • City, State, Zip fields (responsive layout)
      • Country field (defaults to USA)
    • Created By (read-only)
    • Created At timestamp (read-only)
    • Status chip (active/archived)
    • Edit button - Enables inline editing for all fields
    • Save/Cancel buttons - Appear during edit mode

  3. Project Location Map (Issue #236)

    • Interactive Google Map showing project location
    • Red marker at geocoded address
    • Street-level zoom (16)
    • Full-screen toggle button
    • Auto-geocodes address if coordinates missing
    • Updates in real-time when address is edited

Files Tab (/settings/files):

  1. Project Files Table
    • Uploaded PDF files list
    • Columns: File name, Size, Page count, Actions
    • Row actions:
      • Process pages - Opens page ingestion dialog
      • View properties - File metadata details
      • Delete file - Remove file (with confirmation)
    • Upload button to add new files
    • Empty state: "No files uploaded yet" with upload prompt
    • Clicking file row opens page ingestion dialog

File Upload Dialog:

  • Drag-and-drop or click to select
  • File size validation
  • Upload progress indicator
  • Success/error feedback

Page Ingestion Dialog:

  • Select pages to process (all or custom range)
  • Shows already ingested page count
  • Starts async background task
  • Redirects to tasks page to monitor progress

Tasks View​

Accessed via View → Tasks, this view shows background task monitoring:

Layout:

  • Two-tab interface:
    • Active Tasks - Currently running tasks
    • Recent Tasks - Completed/failed tasks

Task Card Information:

  • Task type (Plan Ingestion, Code Applicability, Compliance Report)
  • Progress percentage
  • Current step description
  • Step history (expandable)
  • Cost analysis (tokens used, estimated cost)
  • Actions: Retry, Cancel
  • Status indicators (running, complete, failed)

Features:

  • Real-time progress updates via Firestore
  • Detailed step-by-step history
  • Cost breakdown per task
  • Clear completed tasks button
  • Auto-refresh on task completion

Sharing Settings Features​

Share Dialog​

Accessed via Project → Share or the share button (person_add icon):

Sections:

  1. People with Access

    • List of current project members
    • Shows for each member:
      • Avatar (photo or default)
      • Name and email
      • Current role (Owner, Editor, Prompter, Reader)
    • Role dropdown (only for owners):
      • Change member permissions
      • Remove member access

  2. Add New Members

    • Email input field with validation
    • Email chip display (shows validated email)
    • Role selector dropdown:
      • Reader - Can view project content
      • Prompter - Can use AI prompts
      • Editor - Can edit project content
      • Owner - Full access to project settings and billing
    • "Share" button to send invitation

  3. Actions

    • Copy link - Copy project URL to clipboard
    • Cancel - Close dialog without changes
    • Done - Close dialog after changes

Permission Requirements:

  • Only project Owners can:
    • Invite new members
    • Change member roles
    • Remove members
  • Other roles see read-only member list

Features:

  • Real-time email validation
  • Duplicate email detection
  • Role descriptions on hover
  • Async validation with progress indicator
  • Permission refresh after changes

Billing Page​

Accessed via Billing & Account in user menu or by clicking balance display.

URL: /billing

Sections​

  1. Account Overview Card

    • Available Balance - Current account balance
    • Subscription - Tier chip (Free, Pro, Enterprise)
    • Total Spent - Lifetime spending
    • Tasks Executed - Total task count
    • Action Buttons:
      • "Add Funds" - Top up account balance
      • "Manage Subscription" - Change subscription tier

  2. Transaction History

    • Table of recent transactions
    • Columns:
      • Date & Time
      • Description
      • Amount (debit/credit)
      • Balance after transaction
    • Pagination controls
    • Filter and search options

  3. Usage Statistics

    • Charts and graphs showing:
      • Spending over time
      • Task execution trends
      • Cost per task type
    • Downloadable reports

Error Handling:

  • Shows "Unable to Load Billing Information" if service unavailable
  • Retry button for failed requests
  • Graceful degradation if billing service not configured

Admin Page​

Accessed via Admin Console in user menu (only visible to users with root admin role).

URL: /admin

Access Control: Protected by adminGuard - only users with ROOT_ADMIN role can access

Layout​

Left Navigation Panel:

  • Fixed sidebar with admin sections
  • Currently available:
    • Role Authorizations - Manage user permissions

Main Content Area:

  • Section-specific content based on left nav selection

Role Authorizations Section​

Purpose: Manage global user permissions and access levels across all projects

Tabs:

  1. Raw YAML Tab

    • Direct YAML editor for RBAC configuration
    • Features:
      • User count indicator
      • Unsaved changes indicator
      • Refresh button - Fetch latest from backend
      • Discard button - Revert unsaved changes
      • Save & Apply button - Persist changes to Firebase
    • Syntax highlighting and validation
    • Real-time YAML validation with error messages
    • 25-row textarea for editing

  2. YAML Schema Tab

    • Documentation for RBAC YAML structure
    • Field descriptions and examples
    • Role definitions and permissions
    • Best practices for configuration

Workflow:

  1. View current RBAC configuration
  2. Edit YAML directly in textarea
  3. Validate changes (automatic)
  4. Save and apply to Firebase
  5. Changes propagate to all users

Version Page​

Accessed via direct URL: /version

Purpose: Display detailed version and deployment information for debugging and verification

Sections​

  1. Frontend (Angular App)

    • Version number
    • Git Commit - Clickable link to GitHub commit
    • Git Branch - Clickable link to GitHub branch
    • Build timestamp
    • Environment (dev/test/demo/prod)
    • Node environment

  2. Backend (gRPC Server)

    • Health Status - SERVING/HEALTHY indicator with color coding
    • Git Commit - Clickable link to GitHub commit
    • Git Branch - Clickable link to GitHub branch
    • Build timestamp
    • App version
    • JVM version
    • Uptime (formatted as human-readable duration)
    • Container Image - Clickable link to Google Artifact Registry

  3. Version Source Details (expandable sections)

    📦 Build-time Git Info (from git-commit-id-plugin):

    • Detailed commit information
    • Build metadata
    • All clickable links to GitHub

    ☁️ Cloud Run Deployment Info:

    • Service name (clickable link to Cloud Run console)
    • Revision ID (clickable link to Cloud Run console)
    • Region and configuration

    🔧 Environment Variables:

    • Key environment settings
    • Configuration values

    💻 System Information:

    • OS and runtime details
    • System properties

Actions:

  • Refresh button - Reload version information
  • All Git commits/branches are clickable GitHub links
  • Cloud Run services/revisions are clickable console links

Use Cases:

  • Verify deployment version
  • Debug environment-specific issues
  • Confirm Git commit in production
  • Check backend health status
  • Validate container image

Common User Journeys​

Journey 1: Create and Analyze a New Project​

  1. Start: User lands on home page
  2. Authenticate: Firebase authentication (automatic)
  3. Create Project: Click Project → New
  4. Fill Form:
    • Select PDF file
    • Enter project ID
    • Choose pages (all or custom)
  5. Submit: Click "Create Project"
  6. Wait: Background tasks start (upload, ingestion)
  7. Navigate: Auto-routed to new project
  8. Monitor: View progress in Tasks page
  9. Review: Once ingested, pages appear in left drawer
  10. Analyze: Select pages, run code applicability
  11. Report: Generate compliance report
  12. Download: Export results

Journey 2: Share a Project with Colleague​

  1. Open Project: Navigate to project to share
  2. Open Share Dialog: Click share button or Project → Share
  3. Enter Email: Type colleague's email address
  4. Select Role: Choose permission level (Reader/Editor/Owner)
  5. Send Invitation: Click "Share"
  6. Confirmation: Success message appears
  7. Colleague Access: Colleague receives access immediately

Journey 3: Monitor Background Tasks​

  1. Start Operation: Initiate page ingestion or analysis
  2. Navigate to Tasks: Click View → Tasks or task counter badge
  3. View Active Tasks: See real-time progress
  4. Expand Details: Click to see step-by-step history
  5. Check Costs: View token usage and estimated cost
  6. Wait for Completion: Tasks update automatically
  7. View Results: Navigate back to project to see results

Journey 4: Manage Account Billing​

  1. Check Balance: View balance in top app bar
  2. Navigate to Billing: Click balance or user menu → Billing & Account
  3. View Overview: See balance, subscription, total spent
  4. Check Transactions: Review transaction history
  5. Add Funds: Click "Add Funds" (if needed)
  6. Manage Subscription: Upgrade/downgrade tier

Journey 5: Copy an Existing Project​

  1. Open Source Project: Navigate to project to copy
  2. Open Copy Dialog: Click Project → Make a copy
  3. Configure Copy:
    • Enter new project ID
    • Choose whether to copy sharing settings
    • Select what to copy (files, analyses, etc.)
  4. Submit: Click "Copy Project"
  5. Wait: Background task copies all data
  6. Navigate: Auto-routed to new project copy

Key UI Patterns​

Material Design Principles​

The application follows Material Design 3 guidelines:

  • Elevation: Cards and dialogs use appropriate elevation
  • Color System: Primary (blue), accent (green), warn (red)
  • Typography: Roboto font family with proper hierarchy
  • Spacing: 8px grid system
  • Animations: Smooth transitions and micro-interactions
  • Accessibility: ARIA labels, keyboard navigation, screen reader support

Responsive Design​

  • Desktop: Full-width layout with side drawer
  • Tablet: Collapsible drawer, optimized spacing
  • Mobile: Bottom navigation, stacked layouts

Loading States​

Consistent loading indicators across the app:

  • Spinner: For initial page loads
  • Progress Bar: For determinate progress (file uploads, tasks)
  • Skeleton Screens: For content loading
  • Inline Spinners: For button actions

Error Handling​

User-friendly error messages with:

  • Clear error description
  • Actionable retry buttons
  • Helpful hints for resolution
  • Graceful degradation

Real-Time Updates​

  • Task Progress: Updates via Firestore listeners
  • Balance: Updates after transactions
  • Permissions: Refreshes after sharing changes
  • Project Data: Invalidates cache on modifications

URL Structure​

Updated October 2025 (Issue #243) - Hierarchical parent-child routes for smooth SPA navigation:

/                                           # Landing page (auto-routes)
/projects/:projectId                        # Project parent route
  /projects/:projectId/pages/:pageNum/:tab  # Project page view with tab
  /projects/:projectId/settings             # Project settings (redirects to /overview)
  /projects/:projectId/settings/overview    # Settings overview tab
  /projects/:projectId/settings/files       # Settings files tab
  /projects/:projectId/tasks                # Task monitoring
/billing                                    # Billing and account
/admin                                      # Admin console (admin only)
/version                                    # Version information
/unauthorized                               # Auth error page
/no-access                                  # Access denied page
/error                                      # Server error page

Parent-Child Architecture Benefits:

  • MainViewComponent persists during all /projects/:projectId/* navigation
  • Drawer state maintained across page/settings/tasks switches
  • Smooth transitions without component recreation
  • True Single Page Application experience
  1. Direct URL: Users can bookmark and share project URLs
  2. Menu Navigation: Project and View menus for common actions
  3. Click Navigation: Interactive elements (cards, buttons, links)
  4. Auto-Routing: Intelligent routing based on user state
  5. Breadcrumbs: (Future enhancement) For deep navigation

External Resources​