Kriterion - Secure Evaluation Platform

A Phoenix LiveView application for managing secure, AI-assisted evaluation workflows. Kriterion provides a domain-neutral "spec vs submissions" platform, starting with recruitment use cases.

🎯 Overview

Kriterion is designed to manage multiple parallel Assignments, where each assignment is a reusable evaluation workspace containing:

• Specification/Demand: Job descriptions, project briefs, target profiles
• Stable Context: Team style, evaluation philosophy, domain notes
• Candidate Artifacts: Resumes, proposals, bids, and supporting documents

The system securely stores artifacts, extracts content, runs AI-assisted analysis, generates assessments, and maintains explainable rankings with full audit trails.

✨ Current Features (Phase 1 - Secure Shell)

Security & Authentication

• Bootstrap Setup: First-run master password creation with strength validation
• Unlock Screen: Application-level unlock with encrypted session management
• Lock Controls: Quick lock functionality accessible from any screen
• Visual Security Indicators: Clear locked/unlocked status at all times

Application Shell

• Professional UI: Enterprise-grade interface with Tailwind CSS
• Responsive Navigation: Sticky header with primary navigation
• Assignment List: Empty state with onboarding guidance
• Status Indicators: Real-time security and system status badges

Component Library

• Reusable app header with navigation
• Status badges and indicators
• Form components with validation
• Empty state patterns
• Password strength indicators

🏗️ Architecture

Tech Stack

• Phoenix Framework (v1.8.5)
• Phoenix LiveView (v1.1.26)
• Elixir (v1.18.4)
• PostgreSQL (via Ecto)
• Tailwind CSS v4
• Oban (background jobs - planned)

Project Structure

lib/
├── kriterion/                    # Core business logic
│   └── security.ex              # Security context (bootstrap, unlock)
├── kriterion_web/               # Web interface
│   ├── components/
│   │   ├── core_components.ex   # Reusable UI components
│   │   └── layouts.ex           # App layouts
│   ├── live/
│   │   ├── bootstrap_live.ex    # Initial setup screen
│   │   ├── unlock_live.ex       # Unlock screen
│   │   ├── assignment_live/
│   │   │   ├── index.ex        # Assignment list
│   │   │   └── show.ex         # Assignment detail (placeholder)
│   │   ├── ranking_live/
│   │   │   └── index.ex        # Rankings view (placeholder)
│   │   └── audit_live/
│   │       └── index.ex        # Audit log (placeholder)
│   └── router.ex               # Route definitions
plans/
├── plan-0.1.0.md               # Original architecture plan
├── ui_ux_design.md             # Comprehensive UI/UX design spec
└── ui_implementation_summary.md # Phase 1 implementation summary

🚀 Getting Started

Prerequisites

• Elixir 1.18.4 or higher
• Erlang/OTP 28
• PostgreSQL 14+
• Node.js (for asset compilation)

Installation

1. Clone the repository

   git clone <repository-url>
   cd kriterion

2. Install dependencies

   mix setup

3. Start the Phoenix server

   mix phx.server

   Or inside IEx:

   iex -S mix phx.server

4. Visit the application

   Navigate to http://localhost:4000

First Run

On first visit, you'll be guided through the bootstrap process:

1. Visit http://localhost:4000/bootstrap
2. Create a strong master password (12+ characters recommended)
3. Complete setup to access the main application

📱 Available Routes

Route	Description	Status
/	Assignment list (home)	✅ Implemented
/bootstrap	Initial setup	✅ Implemented
/unlock	Unlock application	✅ Implemented
/assignments/:id	Assignment detail	🚧 Placeholder
/rankings	Rankings dashboard	🚧 Placeholder
/audit	Audit log	🚧 Placeholder

🗺️ Roadmap

Phase 2 - Assignment Management (Next)

• Create/edit/archive/clone assignments
• Spec/context artifact upload
• Encrypted artifact storage
• Artifact metadata display

Phase 3 - Extraction Pipeline

• Text extraction from PDF, DOCX, etc.
• Extraction status display
• Real-time progress updates

Phase 4 - Candidates

• Candidate CRUD operations
• Resume/artifact attachment
• Candidate detail views

Phase 5 - AI Analysis

• LLM provider abstraction
• Provider configuration
• Candidate assessment generation
• Structured score visualization

Phase 6 - Ranking Engine

• Weighted scoring system
• Ranking snapshots
• Comparative dashboard
• Movement tracking

Phase 7 - Hardening

• Session timeout
• Enhanced audit logging
• Export/reporting
• Production optimizations

🎨 Design Philosophy

Visual Design

• Professional & Clean: Enterprise-grade UI with subtle shadows and borders
• Information-Dense: Efficient use of space without overwhelming users
• Status-Aware: Clear visual indicators for security and system state
• Accessible: WCAG AA compliant color contrast and semantic HTML

Color Palette

• Primary: Blue-600 (actions, links, active states)
• Success: Emerald-600 (unlocked, completed)
• Warning: Amber-600 (attention needed)
• Danger: Red-600 (locked, errors)
• Neutral: Slate scale (backgrounds, text, borders)

Interaction Patterns

• Real-time Updates: LiveView for seamless UI updates
• Smooth Transitions: CSS transitions on all interactive elements
• Visual Feedback: Hover states, loading indicators, success confirmations
• Keyboard Support: Full keyboard navigation support

🔒 Security Model

Current Implementation (Phase 1)

• App-Level Unlock: Single master password protects all data
• Session Management: Server-side session tracking
• Visual Indicators: Clear locked/unlocked status
• Secure by Default: All security screens implemented first

Planned Features

• Encrypted Artifact Storage: Per-artifact encryption with AEAD
• Key Derivation: Strong KDF for password-based encryption
• Audit Trail: Immutable log of all significant actions
• Session Timeout: Configurable auto-lock on inactivity

🧪 Development

Running Tests

mix test

Code Quality

mix precommit

📚 Documentation

• Architecture Plan: Original system design
• UI/UX Design: Comprehensive design specification
• Implementation Summary: Phase 1 completion report

🤝 Contributing

This project follows Phoenix and Elixir best practices:

• Code Style: Follow Elixir style guide
• LiveView Patterns: Use LiveView best practices
• Testing: Write tests for all new features
• Documentation: Document public functions and modules
• Security: Never commit secrets or sensitive data

📄 License

[License information to be added]

🙏 Acknowledgments

Built with:

• Phoenix Framework
• Phoenix LiveView
• Tailwind CSS
• Heroicons

---

Current Version: 0.1.0
Status: Phase 1 Complete ✓
Next Phase: Assignment Management