LocalPulse District Growth Web

A Next.js 15 application for district-level commerce and marketing automation.

Overview

LocalPulse District Growth Web is a modern web application built with Next.js 15, TypeScript, and Tailwind CSS. It provides real-time data-driven insights and action recommendations for local businesses and district associations.

Features

• Real-time Signal Monitoring: Displays current traffic capacity and environmental conditions
• Smart Action Recommendations: AI-powered suggestions for timely business actions
• ROI Tracking: Monitor the effectiveness of implemented actions
• QR Code Generation: Create printable promotional materials
• Demo Presets: Quick-start scenarios for different weather and traffic conditions

Architecture

Monorepo Structure

localpulse/
├── apps/
│   └── district-growth-web/          # Next.js 15 web application
├── packages/
│   ├── types/                        # Shared TypeScript types
│   ├── api-client/                   # API client with fetch wrappers
│   ├── ui-shared/                     # Reusable React components
│   ├── config/                         # Shared configuration
│   └── qr-kit/                         # QR code generation utilities
├── tools/
│   └── openapi-gen.mjs              # OpenAPI type generation
└── tests/
    └── e2e/                          # End-to-end tests

Technology Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• Package Manager: pnpm with workspaces
• Build Tool: Turborepo
• Testing: Vitest (unit), Playwright (E2E)
• Linting: ESLint + Prettier

Getting Started

Prerequisites

• Node.js 18+
• pnpm 9+
• Python 3.11+ (for API)

Installation

# Install dependencies
pnpm install

# Generate types from OpenAPI spec
pnpm types:gen

# Start development servers
pnpm dev

Development

# Start both API and web servers
pnpm dev

# Start only web server
pnpm dev:web

# Start only API server
pnpm dev:api

Building

# Build all packages and applications
pnpm build

# Build specific package
pnpm --filter @localpulse/ui-shared build

Testing

# Run all tests
pnpm test

# Run unit tests only
pnpm test:unit

# Run E2E tests only
pnpm test:e2e

# Run tests with UI
pnpm test:ui

Linting and Formatting

# Check code style
pnpm lint

# Fix auto-fixable issues
pnpm lint:fix

# Check formatting
pnpm format:check

# Format code
pnpm format

Packages

@localpulse/types

Shared TypeScript types for the entire monorepo, including:

• API response types
• UI component props
• Domain models

@localpulse/api-client

Fetch wrapper with:

• Timeout handling
• Exponential backoff retry
• Runtime validation
• Demo data fallback

@localpulse/ui-shared

Headless React components:

• SignalMeter - Traffic capacity display
• ReasonBadge - Trigger reason indicators
• ActionCard - Action recommendation tiles
• RoiLamp - Feedback countdown timer
• QrPoster - Printable QR code generation

@localpulse/config

Shared configuration:

• API base URLs
• Request timeouts
• Environment-specific settings

@localpulse/qr-kit

QR code utilities:

• SVG-based QR generation
• Short link creation
• Print-ready layouts

Application Pages

/

Main dashboard showing:

• Current signal meter
• Top 3 action recommendations
• Health status indicator

/demo

Interactive demo with presets:

• Rain now scenario
• School dismissal scenario
• Closing hour scenario

/pricing

Pricing tiers for different organization sizes:

• Starter (4 triggers)
• Pro (12 triggers)
• District (10 stores)

/partners/boards

Information for DOOH/CMS operators:

• Integration options
• Revenue sharing details
• Technical specifications

/associations

Value proposition for district associations:

• Success stories
• Implementation features
• Performance metrics

/cases/[slug]

Dynamic case study pages:

• ximen-rain - Rainy day success story
• school-dismissal - After-school program results

Testing Strategy

Unit Testing

• Component rendering tests
• Props validation
• Accessibility compliance
• Snapshot testing

End-to-End Testing

• Critical user flows
• Cross-browser compatibility
• Mobile responsiveness
• API integration

Deployment

The application is designed to be deployed to Vercel, Netlify, or any Node.js hosting platform.

Environment Variables

NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.