Technical Architecture & Scope Document

Prototype: AI-Enabled 5-Theme Culture Management System

Phase: Prototype / POC Total Est. Hours: 75-95 Duration: 5 Weeks
Ahmed Reda Software Engineer April 19, 2026

1. Executive Engineering Summary

This document defines the exact technical scope, functional modules, technology stack, and delivery roadmap for the ElKattan Consulting AI Culture System Prototype. The objective is to build a robust, scalable "Vertical Slice" that proves the system's ability to ingest complex Excel data, calculate organizational gaps deterministically, and leverage Generative AI (Claude 3.5 Sonnet) to orchestrate consulting tactics matching the firm's proprietary methodology.

2. Prototype Scope Definition (Vertical Slice)

What is a Vertical Slice?

Instead of building the entire system superficially, the prototype will implement 100% of the functionality for One Core Value (e.g., Accountability / المسؤولية). This proves the complete data flow from end to end without spreading resources thin.

✅ In-Scope for Prototype

  • Parsing structural and survey data from the "COE Culture Assessment" Excel files.
  • Automated Actual vs. Desired Gap Calculation for criteria under the selected Core Value.
  • AI generation of Contextual Tactics (Behaviors, Practices, Mindsets, Communication).
  • Interactive UI for consultants to review, edit, and approve AI outputs.
  • Automated generation and export of a standard PPTX/Word presentation.

3. Core System Architecture & Data Flow

1. Ingestion ExcelJS Parser
→
2. Logic Core Node.js / Gap Math
↔
3. AI Engine Claude 3.5 Sonnet
→
4. Presentation Next.js / PptxGenJS

4. Detailed Functional Modules

Module 1: Data Ingestion & Normalization Engine

  • Excel Upload Interface: Secure drag-and-drop UI for `.xlsx` files.
  • Sheet Parsing: Automated reading of specific sheets (e.g., "1.Data", "11.Org Results").
  • Schema Validation: Ensuring data integrity using strict Zod schemas before processing.
  • Data Normalization: Converting tabular Excel data into nested JSON objects suitable for backend logic.

Module 2: Analytical Calculation Core

  • Deterministic Logic: Hardcoded mathematical algorithms to calculate gaps (Desired Score - Actual Score).
  • Severity Calibration: Categorizing gaps automatically into bands (Low, Moderate, High, Critical) based on predefined business rules.
  • Context Packaging: Compiling the calculated results into a structured prompt-context package.

Module 3: AI Orchestration & Generation

  • Prompt Engineering: Development of highly optimized, few-shot prompts in Arabic to guide the AI.
  • Tone of Voice Enforcement: System prompts designed to strictly mimic ElKattan Consulting's professional tone.
  • Structured Outputs (JSON): Forcing the Claude API to return tactics in strict JSON format (Tactic Name, Description, Target Audience, Impact) to prevent UI breakage.

Module 4: Presentation & Export Engine

  • Consultant Dashboard (Next.js): A clean, responsive data table viewing interface.
  • Inline Editor: Ability for the SME (Subject Matter Expert) to edit AI-generated text directly in the browser.
  • PPTX Generator: Utilizing `PptxGenJS` to map the final approved JSON data into branded PowerPoint slides dynamically.

5. Comprehensive Technology Stack

Category Technology Engineering Justification
Frontend / Framework Next.js 14 (App Router)
React, TypeScript		 Provides a unified Full-Stack environment. TypeScript ensures end-to-end type safety, drastically reducing runtime errors.
UI / Styling Tailwind CSS
Shadcn UI components		 Enables rapid development of highly professional, enterprise-grade B2B interfaces without writing CSS from scratch.
Data & Validation ExcelJS, Zod ExcelJS handles complex, multi-sheet, formula-heavy workbooks safely. Zod validates the extracted JSON structure before feeding it to the AI.
Artificial Intelligence Anthropic API (Claude 3.5 Sonnet) Superior contextual understanding of large documents (BRD) and unmatched fluency in formal Arabic consulting terminology compared to GPT-4.
Export Generation PptxGenJS, docx Client-side or Node-based libraries capable of generating native Microsoft Office files programmatically from JSON data.

6. Granular Sprint Plan & Timeline (75 - 95 Hours)

Sprint 1: Architecture & Data Ingestion

Estimated: 18 - 22 Hours

Initialize Next.js project with Clean Architecture. Setup Git repository. Build the UI for file uploading. Develop the `ExcelJS` parsing service to extract Actual and Desired scores for the selected Core Value. Implement `Zod` validation schemas. Output: Functional data extraction pipeline.

Sprint 2: Gap Math & AI Integration Core

Estimated: 20 - 24 Hours

Build the deterministic Gap Calculator service. Design the core AI Prompts embedding the 5-Theme methodology. Integrate the Anthropic API. Implement retry logic and error handling. Map the LLM output to strongly typed TypeScript interfaces. Output: Raw AI-generated tactics logged to the console.

Sprint 3: Consultant Interaction UI

Estimated: 18 - 22 Hours

Develop the frontend Dashboard. Create visual indicators for gap severity (Color-coded badges). Build the interactive "Tactics Review Grid" allowing consultants to approve, edit, or regenerate specific AI outputs. Output: Fully functional web interface.

Sprint 4: Export Automation Engine

Estimated: 15 - 18 Hours

Integrate `PptxGenJS`. Map the approved state of the Dashboard into slide coordinates. Generate a basic branded PowerPoint deck containing the findings and tactics. Output: One-click "Export to PPTX" functionality.

Sprint 5: Testing, QA & Refinement Buffer

Estimated: 8 - 12 Hours

Utilize the 20% buffer for End-to-End (E2E) testing. Refine the AI Prompt based on SME (Subject Matter Expert) feedback to adjust the "Tone of Voice". Prepare the final codebase and a Loom video demo for management presentation.

7. Resource & Infrastructure Costs (Prototype Phase)

To ensure maximum engineering velocity and eliminate technical bottlenecks during the 5-week sprint, the following tools and operational resources are required. The costs reflect a lean, pay-as-you-go approach suited for MVP development.

Development Environment (IDE)

Required for high-speed AI-assisted engineering and complex context management.

  • Cursor Pro Plus MANDATORY
    $60
    / month

    Provides 1,500 premium fast requests. This tier is strictly required because the context window for this project is massive (the BRD document + complex Excel business logic). A lower tier will hit rate limits immediately, blocking development.

  • Cursor Pro (Alternative)
    $20
    / month

    Provides only 500 requests. Not recommended for this project's intensity.

Operational AI & Cloud Hosting

System runtime costs associated with generating consulting data and hosting the UI.

  • Claude 3.5 Sonnet API (Anthropic)
    $50 - $100
    / estimated total

    This is the core "Brain" of the application. Billed strictly on a Pay-as-you-go basis. This covers the token consumption during prompt engineering, testing, and final tactic generation.

  • Cloud Hosting (Vercel)
    $0
    / Prototype Phase

    The Free Tier (Hobby) provided by Vercel is fully sufficient to host the MVP dashboard for testing and management demonstration.

8. Operational Prerequisites (From Client)

To ensure Sprint 1 commences without blockers, ElKattan Consulting must provide:

Strictly Confidential — Authored by Ahmed Reda for ElKattan Consulting © 2026
Designed for high-performance engineering execution.