NEOMapper

AI-powered field mapping tool for NEOGOV. Maps source JSON fields to target schema fields using AI-generated suggestions, with human review and rule generation.

Status

• Frontend: MVP complete with mock data. 121 tests passing across 11 test suites.
• Backend: Staged pipeline architecture implemented. 580 tests passing (541 unit + 39 integration).

The frontend runs independently in mock mode by default. Set USE_MOCKS = false in Settings to connect to the backend API.

Tech Stack

• Frontend: React 18 + TypeScript + Vite + Tailwind CSS + NEOGOV design library (shadcn/ui port)
• Backend: C# / .NET 8 Clean Architecture, SQLite, OpenAI
• State: React Context (useAppState()) with localStorage persistence
• Routing: React Router v6 (12 pages)
• Testing: Vitest + Testing Library (frontend), xUnit + FluentAssertions + Moq (backend)

Quick Start

Frontend

cd ui
npm install
npm run dev      # http://localhost:5173
npm run test     # run all tests
npm run build    # typecheck + production build

Backend

dotnet build
dotnet test      # 580 tests
dotnet run --project src/NEOMapper.API   # http://localhost:5000

Configure OpenAI:ApiKey in src/NEOMapper.API/appsettings.json for real AI calls. Without it, the stub provider returns hardcoded candidates.

Project Structure

ui/                           # Frontend application (Vite SPA)
  src/pages/                  # 12 screens (10 workflow + Settings + Gallery)
  src/components/             # Atomic design: atoms, molecules, organisms
  src/state/                  # React Context state management
  src/api/                    # API client with mock implementations
  src/types/                  # Centralized type definitions (single source of truth)
src/                          # Backend (.NET 8)
  NEOMapper.Domain/           # Entities, enums — zero dependencies
  NEOMapper.Application/      # Interfaces, services, staged pipelines
    KnowledgeBase/            # Signal extraction, aggregation, retrieval
    Suggestions/              # Suggestion engine (prompt builder, parser, coordinator)
    Rules/                    # Rule generation engine (prompt builder, parser, coordinator)
    Shared/                   # Cross-cutting (prompt sanitizer)
  NEOMapper.Infrastructure/   # SQLite repos, OpenAI client, static knowledge
  NEOMapper.API/              # Controllers, DI, middleware
tests/                        # Backend tests
  NEOMapper.UnitTests/        # 541 unit tests
  NEOMapper.IntegrationTests/ # 39 integration tests
design-library/               # NEOGOV component library (50 components)
docs/                         # All documentation
  documentation/              # Architecture, API, data contracts, specs

Architecture

The backend uses a staged pipeline pattern for both AI engines:

KBRetriever -> PromptBuilder -> LLMClient -> ResponseParser -> PostProcessor -> Coordinator

• Knowledge Base: Dual-layer — immutable session snapshots (Layer 1) + derived entries (Layer 2, batch rebuilt)
• Suggestion Engine: Full-schema single-pass, KB-enhanced prompts
• Rule Generation Engine: Static knowledge tiers + validation retry loop

The frontend is a fully independent SPA. All data persists in localStorage during mock mode. The API client layer abstracts mock vs live, so switching to a real backend requires no UI changes.

Documentation

See docs/README.md for the full index. Key documents:

• ARCHITECTURE.md — System architecture and design decisions
• API_REFERENCE.md — All REST endpoints with request/response examples
• DATA_CONTRACTS.md — Type definitions and data shapes
• UI_DEVELOPMENT_GUIDE.md — Frontend utilities, state, API client reference
• DEPLOYMENT.md — Build and deployment guide

NEOMapper2Temp