DOCS-01: Configuration & Project Setup

Instance 1 Documentation Project: Pronghorn - AI-Powered Enterprise Application Platform Focus: Root configuration, build system, and development setup

Project Overview
Technology Stack
Build System Configuration
TypeScript Configuration
Tailwind CSS & Styling
Environment Variables
Code Quality & Linting
PWA Configuration
Development Workflow

Project Overview

Pronghorn is an AI-powered software development platform built by the Government of Alberta, Ministry of Technology and Innovation.

Core Identity

Package Name: vite_react_shadcn_ts
Version: 0.0.0 (Alpha)
License: MIT
Type: ESM (ECMAScript Module)
Live URL: https://pronghorn.red

Architecture Philosophy

Standards-first, agentic AI platform that transforms unstructured requirements into production-ready code with complete traceability.

Technology Stack

Frontend Framework

Technology	Version	Purpose
React	^18.3.1	UI framework
React DOM	^18.3.1	DOM rendering
TypeScript	^5.8.3	Type safety
Vite	^5.4.19	Build tool & dev server

Rationale: React 18+ provides concurrent rendering capabilities essential for real-time collaboration features. Vite offers lightning-fast HMR (Hot Module Replacement) critical for developer experience.

UI Component Libraries

Core UI System

"@radix-ui/*": "^1.x - ^2.x"  // 18 Radix UI primitives

Radix UI Components Used:

Accordion, Alert Dialog, Avatar, Checkbox
Collapsible, Context Menu, Dialog, Dropdown Menu
Hover Card, Label, Menubar, Navigation Menu
Popover, Progress, Radio Group, Scroll Area
Select, Separator, Slider, Slot
Switch, Tabs, Toast, Toggle, Toggle Group, Tooltip

Design System Foundation:

shadcn/ui: Component architecture pattern (not a dependency, uses copy-paste approach)
class-variance-authority (^0.7.1): Type-safe variant styling
clsx (^2.1.1): Conditional className composition
tailwind-merge (^2.6.0): Intelligent Tailwind class merging

State Management & Data Fetching

Library	Version	Purpose
@tanstack/react-query	^5.83.0	Server state management
react-hook-form	^7.61.1	Form state management
@hookform/resolvers	^3.10.0	Schema validation for forms
zod	^3.25.76	TypeScript-first schema validation

Architecture Pattern: Server state managed by React Query, client UI state managed by React Context (see DOCS-07-StateManagement.md).

Backend & Database

Technology	Version	Purpose
@supabase/supabase-js	^2.81.1	PostgreSQL client & real-time subscriptions

Backend Architecture:

Supabase Edge Functions (Deno runtime)
PostgreSQL database with Row Level Security (RLS)
Real-time subscriptions for collaborative features

Visualization & Diagramming

Library	Version	Purpose	Bundle Size
reactflow	^11.11.4	Interactive node-based canvas (24+ node types)	~300KB
d3	^7.9.0	Data visualization primitives	~500KB
recharts	^2.15.4	Chart components	~400KB
react-force-graph-2d	^1.29.0	Force-directed graph layouts	~150KB

Use Cases:

ReactFlow: Visual architecture design canvas (WEB_COMPONENT, API_ROUTER, DATABASE nodes)
D3: Custom Venn diagrams in audit mode
Recharts: Dashboard analytics
Force Graph: Dependency visualization

Document Processing

Library	Version	Purpose
pdfjs-dist	^4.8.69	PDF parsing & rendering
mammoth	^1.11.0	.docx to HTML conversion
docx	^9.5.1	DOCX file generation
exceljs	^4.4.0	Excel spreadsheet manipulation
jspdf	^3.0.4	PDF generation
jszip	^3.10.1	ZIP file handling

Feature: AI-powered document import for requirements extraction.

Code & Markdown Editing

Library	Version	Purpose
@monaco-editor/react	^4.7.0	VSCode-based code editor
react-markdown	^10.1.0	Markdown rendering
remark-gfm	^4.0.1	GitHub Flavored Markdown support

Use Case: Autonomous coding agent with syntax highlighting and IntelliSense.

Utility Libraries

Library	Version	Purpose
date-fns	^3.6.0	Date manipulation
diff	^8.0.2	Text diffing for version control UI
lucide-react	^0.462.0	Icon library (1000+ icons)
sonner	^1.7.4	Toast notifications
vaul	^0.9.9	Mobile drawer component
cmdk	^1.1.1	Command palette (⌘K menu)
perfect-freehand	^1.2.2	Freehand drawing on canvas
html-to-image	^1.11.13	Canvas to image conversion

Theming & Styling

Library	Version	Purpose
next-themes	^0.3.0	Dark mode management
tailwindcss	^3.4.17	Utility-first CSS
@tailwindcss/typography	^0.5.19	Prose styling for markdown
tailwindcss-animate	^1.0.7	Animation utilities

Build System Configuration

Vite Configuration (vite.config.ts)

Development Server

server: {
  host: "::",      // IPv6 support
  port: 8080,      // Default port
}

Build Optimization Strategy

Manual Code Splitting - Optimized for HTTP/2 parallel loading:

manualChunks: {
  "vendor-react": ["react", "react-dom", "react-router-dom", "@tanstack/react-query"],
  "vendor-monaco": ["@monaco-editor/react"],           // ~1.5MB
  "vendor-pdf": ["pdfjs-dist"],                        // ~2MB
  "vendor-reactflow": ["reactflow"],                   // ~300KB
  "vendor-charts": ["recharts"],                       // ~400KB
  "vendor-office": ["exceljs", "mammoth", "docx", "jszip"], // ~1MB
  "vendor-radix": [/* 18 Radix UI packages */],        // ~600KB
}

Bundle Size Strategy:

Core app chunk: <500KB (Brotli compressed)
Vendor chunks: Lazy-loaded on feature use
Total uncompressed: ~8-10MB (all vendors)
Compressed (Brotli): ~2-3MB

Compression Configuration

// Brotli (primary) - ~25-30% better than gzip
viteCompression({
  algorithm: "brotliCompress",
  ext: ".br",
  threshold: 1024,  // Only compress files >1KB
}),

// Gzip (fallback for older browsers)
viteCompression({
  algorithm: "gzip",
  ext: ".gz",
  threshold: 1024,
})

Performance: Brotli achieves 80-85% compression on JS bundles.

Path Aliases

resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
  },
}

Usage Examples:

import { Button } from "@/components/ui/button"
import { useProject } from "@/hooks/useProject"
import { supabase } from "@/integrations/supabase/client"

Build Modes

Command	Mode	Use Case
`npm run dev`	development	Local development with HMR
`npm run build`	production	Production build (minified, tree-shaken)
`npm run build:dev`	development	Development build (source maps, no minification)
`npm run preview`	production	Preview production build locally

TypeScript Configuration

Configuration File Structure

tsconfig.json (root)
├── tsconfig.app.json (application code)
└── tsconfig.node.json (Vite config)

Root Config (tsconfig.json)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] },
    "noImplicitAny": false,
    "noUnusedParameters": false,
    "skipLibCheck": true,
    "allowJs": true,
    "noUnusedLocals": false,
    "strictNullChecks": false
  }
}

Philosophy: Pragmatic over strict - Allows rapid AI-generated code iteration without type-checking friction.

Application Config (tsconfig.app.json)

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "strict": false,  // Intentionally permissive
    "noEmit": true    // Vite handles compilation
  }
}

Key Decisions:

Target ES2020: Modern browser support (95%+ global coverage)
Bundler Module Resolution: Optimized for Vite
No Emit: Vite SWC plugin handles transpilation

Node Config (tsconfig.node.json)

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023"],
    "strict": true,  // Stricter for build scripts
  },
  "include": ["vite.config.ts"]
}

Tailwind CSS & Styling

Configuration (tailwind.config.ts)

Dark Mode Strategy

darkMode: ["class"]  // Manual toggle via next-themes

Implementation: <html class="dark"> applied by theme provider.

Color System (CSS Variables)

Design System Tokens:

colors: {
  background: "hsl(var(--background))",
  foreground: "hsl(var(--foreground))",
  primary: {
    DEFAULT: "hsl(var(--primary))",
    foreground: "hsl(var(--primary-foreground))",
    hover: "hsl(var(--primary-hover))",
  },
  // ... standard shadcn/ui palette

  // Custom status colors for workflow modes
  "status-design": "hsl(var(--status-design))",
  "status-audit": "hsl(var(--status-audit))",
  "status-build": "hsl(var(--status-build))",
}

CSS Variable Location: src/index.css

Custom Animations

keyframes: {
  "slide-in-left": { /* ... */ },
  "slide-out-left": { /* ... */ },
  "slide-in-right": { /* ... */ },
  "slide-out-right": { /* ... */ },
  "float": {
    "0%, 100%": { transform: "translateY(0)" },
    "50%": { transform: "translateY(-10px)" }
  },
}

Use Cases: Sidebar transitions, modal animations, floating UI elements.

Responsive Breakpoints

screens: {
  "2xl": "1400px",  // Custom max-width container
}
// Default Tailwind breakpoints (sm, md, lg, xl) inherited

Plugins

plugins: [
  require("tailwindcss-animate"),      // Utility animation classes
  require("@tailwindcss/typography"),  // Prose styling
]

Typography Plugin: Enables .prose classes for rendered markdown content.

shadcn/ui Configuration (components.json)

{
  "style": "default",
  "rsc": false,               // Not using React Server Components
  "tsx": true,
  "tailwind": {
    "baseColor": "slate",
    "cssVariables": true,     // CSS var-based theming
    "prefix": ""              // No class prefix
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Component Installation:

npx shadcn-ui@latest add button
# Copies component to @/components/ui/button.tsx

Environment Variables

Configuration (.env)

VITE_SUPABASE_PROJECT_ID="obkzdksfayygnrzdqoam"
VITE_SUPABASE_URL="https://obkzdksfayygnrzdqoam.supabase.co"
VITE_SUPABASE_PUBLISHABLE_KEY="eyJhbGci..."  # Public anon key
VITE_ADMIN_KEY="your-admin-key-here"         # Super admin access

Environment Variable Naming Convention

Vite Requirement: All client-side env vars MUST be prefixed with VITE_

Access Pattern:

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL

Security Notes

Public Keys:

VITE_SUPABASE_PUBLISHABLE_KEY: Safe to expose (anon role with RLS)
Supabase RLS policies enforce authorization

Private Keys (NOT in .env, stored in Supabase secrets):

Service role key (full database access)
AI provider API keys (Anthropic, Google, xAI)

Development vs Production

Variable	Development	Production
`VITE_SUPABASE_URL`	Dev project	Production project
`VITE_ADMIN_KEY`	Local override	Secure vault value

Code Quality & Linting

ESLint Configuration (eslint.config.js)

export default tseslint.config(
  { ignores: ["dist"] },
  {
    extends: [
      js.configs.recommended,
      ...tseslint.configs.recommended
    ],
    plugins: {
      "react-hooks": reactHooks,
      "react-refresh": reactRefresh,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
      "@typescript-eslint/no-unused-vars": "off",  // Disabled for AI code gen
    },
  },
);

Philosophy: Enforces React best practices (hooks rules) but allows flexibility for rapid prototyping.

PostCSS Configuration (postcss.config.js)

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},  // Auto-adds vendor prefixes (-webkit-, -moz-)
  },
};

Processing Flow: Tailwind CSS → Autoprefixer → Minification (in production)

PWA Configuration

Manifest (vite.config.ts)

VitePWA({
  registerType: "prompt",  // User must approve update
  manifest: {
    name: "Pronghorn - AI-Powered Enterprise Application Platform",
    short_name: "Pronghorn",
    theme_color: "#0a0a0a",
    background_color: "#0a0a0a",
    display: "standalone",
    start_url: "/",
    icons: [
      { src: "/pwa-192x192.png", sizes: "192x192", type: "image/png" },
      { src: "/pwa-512x512.png", sizes: "512x512", type: "image/png" },
    ],
  },
})

Service Worker Strategy

Workbox Configuration:

Precaching (Install-time):

globPatterns: ["**/*.{css,html,ico,png,svg,woff2}"]
globIgnores: ["**/vendor-*.js"]  // Don't precache vendor chunks
maximumFileSizeToCacheInBytes: 2 * 1024 * 1024  // 2 MiB

Runtime Caching:

Pattern	Strategy	Cache Duration
Vendor chunks (`vendor-*.js`)	CacheFirst	30 days
Page chunks (`*-[hash].js`)	StaleWhileRevalidate	7 days
Supabase API	NetworkFirst	1 hour
Google Fonts	CacheFirst	1 year

Performance Impact:

First Load: ~3-5 seconds (download + cache)
Return Visits: <500ms (cached assets)
Offline: Full UI available, data requires connection

Update Strategy

registerType: "prompt"
skipWaiting: false
clientsClaim: true

User Experience:

New version detected
Prompt shown: "Update available"
User clicks "Update" → Service worker activates
Page reloads with new version

Development Workflow

Project Scripts

"scripts": {
  "dev": "vite",                              // Start dev server (http://localhost:8080)
  "build": "vite build",                      // Production build
  "build:dev": "vite build --mode development", // Dev build (source maps)
  "lint": "eslint .",                         // Lint all .ts/.tsx files
  "preview": "vite preview"                   // Preview prod build
}

Local Development Setup

Prerequisites:

Node.js >= 18.x
npm >= 9.x (or bun >= 1.x)

Installation:

npm install
# or
bun install  # Faster alternative (note: bun.lockb exists)

Start Development Server:

npm run dev
# Server: http://localhost:8080

Environment Setup:
- Copy .env and update VITE_ADMIN_KEY if needed
- Default Supabase project works out-of-the-box for testing

Hot Module Replacement (HMR)

Vite + React SWC Plugin:

Speed: <100ms for component updates
State Preservation: React Fast Refresh maintains component state
Error Recovery: Automatic recovery from runtime errors

Development Plugins:

mode === "development" && componentTagger()  // Lovable.dev integration

Build Output Structure

dist/
├── assets/
│   ├── index-[hash].css           # Main stylesheet
│   ├── index-[hash].js            # Main app chunk
│   ├── vendor-react-[hash].js     # React ecosystem
│   ├── vendor-monaco-[hash].js    # Code editor
│   ├── vendor-pdf-[hash].js       # PDF processing
│   ├── vendor-radix-[hash].js     # UI components
│   └── ...                        # Other vendor chunks
├── index.html                     # Entry point
└── manifest.webmanifest           # PWA manifest

Performance Budgets

Metric	Target	Actual
First Contentful Paint	<1.5s	~1.2s
Time to Interactive	<3.5s	~3.0s
Total Bundle Size (gzip)	<2MB	~1.8MB
Lighthouse Score	>90	92-95

HTML Entry Point

Meta Configuration (index.html)

SEO Optimization:

<title>Pronghorn - AI-Powered Enterprise Application Platform</title>
<meta name="description" content="Transform unstructured requirements into traceable, compliant applications...">
<link rel="canonical" href="https://pronghorn.red/">

Open Graph (Social Sharing):

<meta property="og:image" content="https://pronghorn.red/og-image.png">
<meta property="og:type" content="website">

PWA Meta Tags:

<meta name="theme-color" content="#0a0a0a">
<meta name="apple-mobile-web-app-capable" content="yes">

Application Entry:

<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>

Key Architectural Decisions

1. Why Vite over Create React App?

10x faster HMR
Native ESM support
Built-in code splitting
Modern by default (no polyfills needed)

2. Why Bun lockfile exists alongside npm?

Compatibility: Both package managers supported
Bun: ~3x faster installation
npm: Standard CI/CD compatibility

3. Why TypeScript strict mode disabled?

AI Code Generation: Allows rapid iteration without type errors blocking development
Pragmatic Trade-off: Runtime safety via Zod validation at boundaries

4. Why manual code splitting instead of automatic?

HTTP/2 Optimization: Browsers can parallel-download optimized chunks
Cache Efficiency: Vendor code rarely changes, long cache TTL
Predictable Performance: Avoid automatic chunk thrashing

5. Why shadcn/ui over Material-UI or Chakra?

Full Control: Copy-paste components (no runtime dependency)
Tailwind Native: No CSS-in-JS overhead
Tree Shaking: Only bundle used code

Dependencies Audit Summary

Total Dependencies: 43 production + 15 dev Largest Dependencies:

pdfjs-dist (~2MB) - PDF processing
@monaco-editor/react (~1.5MB) - Code editor
reactflow (~300KB) - Canvas
recharts (~400KB) - Charts

Security:

All dependencies use Semantic Versioning (^x.y.z)
Automated updates via Dependabot (GitHub)
No known critical vulnerabilities (as of build date)

Next Steps for Developers

Read Component Documentation: See DOCS-04-UIComponents.md
Understand State Management: See DOCS-07-StateManagement.md
Explore Backend Integration: See DOCS-03-SupabaseBackend.md
Review Architecture: See DOCS-09-Architecture.md

Documentation Generated: Instance 1 - Configuration & Setup Last Updated: 2026-01-06 Maintainer: Pronghorn Documentation Team

FilesExpand file tree

DOCS-01-Configuration.md

Latest commit

History