Skip to content

replit.md

Latest commit

 

History

History
128 lines (99 loc) · 5.18 KB

replit.md

File metadata and controls

128 lines (99 loc) · 5.18 KB

Secure Authentication Application

Overview

This is a full-stack web application that implements secure authentication using AWS Cognito with multi-factor authentication (MFA). The application features a React frontend with shadcn/ui components and an Express.js backend, utilizing PostgreSQL for data storage via Drizzle ORM.

System Architecture

Frontend Architecture

  • Framework: React 18 with TypeScript
  • Routing: Wouter for client-side routing
  • State Management: TanStack React Query for server state management
  • UI Components: shadcn/ui component library with Radix UI primitives
  • Styling: Tailwind CSS with custom CSS variables for theming
  • Build Tool: Vite for development and production builds

Backend Architecture

  • Framework: Express.js with TypeScript
  • Authentication: AWS Cognito for user authentication and TOTP-based MFA
  • Database: PostgreSQL with Drizzle ORM for type-safe database operations
  • Session Management: Custom session handling with database storage
  • API Design: RESTful API endpoints for authentication flows

Data Storage

  • Primary Database: PostgreSQL (configured via Neon serverless)
  • ORM: Drizzle ORM with schema-first approach
  • Migration System: Drizzle Kit for database migrations
  • Schema Location: Shared schema definitions in /shared/schema.ts

Key Components

Authentication Flow

  1. Login Phase: User credentials validated against AWS Cognito
  2. MFA Setup: TOTP secret generation and QR code display for first-time users
  3. MFA Verification: Google Authenticator or similar app verification
  4. Session Management: Custom session handling with database persistence

Database Schema

  • Users Table: Basic user information (id, username, password)
  • Auth Sessions Table: Session management with MFA state tracking
    • Session ID, username, Cognito session data
    • TOTP secret storage, MFA verification status
    • Timestamps for session lifecycle management

Frontend Pages

  • Login Page (/): Email/password authentication form
  • MFA Page (/mfa): TOTP setup and verification interface
  • Success Page (/success): Post-authentication confirmation
  • 404 Page: Error handling for invalid routes

API Endpoints

  • POST /api/login: Initial authentication with Cognito
  • POST /api/mfa: TOTP verification and session completion

Data Flow

  1. User submits credentials on login page
  2. Backend validates with AWS Cognito
  3. If MFA required, TOTP secret generated and QR code returned
  4. User scans QR code with authenticator app
  5. User enters TOTP code for verification
  6. Backend validates TOTP and completes authentication
  7. User redirected to success page upon completion

External Dependencies

AWS Services

  • AWS Cognito: User pool management and authentication
  • AWS SDK: Cognito Identity Provider client for backend integration

Database

  • Neon: Serverless PostgreSQL database hosting
  • Connection: Environment variable DATABASE_URL required

Authentication Libraries

  • speakeasy: TOTP secret generation and validation
  • qrcode: QR code generation for authenticator app setup
  • nanoid: Secure session ID generation

UI Libraries

  • Radix UI: Headless UI primitives for accessibility
  • Lucide React: Icon library for consistent iconography
  • React Hook Form: Form state management with validation
  • Zod: Runtime type validation and schema definition

Deployment Strategy

Development Environment

  • Runtime: Node.js 20 with ES modules
  • Database: PostgreSQL 16 via Replit modules
  • Development Server: Vite dev server with HMR
  • API Server: tsx for TypeScript execution in development

Production Build Process

  1. Frontend built with Vite to dist/public
  2. Backend bundled with esbuild to dist/index.js
  3. Static assets served from built frontend
  4. Database migrations applied via drizzle-kit push

Environment Configuration

  • Development: NODE_ENV=development with tsx execution
  • Production: NODE_ENV=production with compiled JavaScript
  • Database: Requires DATABASE_URL environment variable
  • AWS: Requires AWS_REGION, COGNITO_USER_POOL_ID, COGNITO_CLIENT_ID

Hosting

  • Platform: Replit with autoscale deployment target
  • Port Configuration: Internal port 5000, external port 80
  • Build Command: npm run build
  • Start Command: npm run start

Preferred Communication Style

Preferred communication style: Simple, everyday language.

Recent Changes

  • June 22, 2025: Initial authentication system setup with AWS Cognito integration
  • June 22, 2025: Implemented TOTP-based MFA with QR code generation using actual Cognito user pool
  • June 22, 2025: Migrated to AWS Amplify for simplified authentication and session management
  • June 22, 2025: Fixed MFA verification flow using Amplify's built-in methods
  • June 22, 2025: Streamlined authentication with proper session handling
  • June 22, 2025: Completed working authentication system with local TOTP verification
  • June 22, 2025: Created comprehensive README.md for local development setup

Changelog

  • June 22, 2025: Full-stack authentication application with AWS Cognito and MFA completed