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 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 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 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.
Export Generation PptxGenJS, docx Client-side or Node-based libraries capable of generating native Microsoft Office files programmatically from JSON data.

6. High-Level Execution & Milestone Plan (75 - 95 Hours)

Agile Delivery Methodology: The 5-week development timeline is structured around 3 major Milestones aligned with the BRD phases. Each Milestone concludes with a formal Review Checkpoint to validate engineering outputs, refine AI behavior, and secure SME approval.

1

Data Engine & Analytics Foundation

Establishing infrastructure and ingesting culture assessment files
BRD Phase 1: Readiness
📅 Sprints & Tasks
Sprint 1 (Week 1)
  • Setup Clean Architecture (Next.js/Node.js).
  • Develop Excel data ingestion engine.
  • Design strict JSON Data Schemas.
Sprint 2 (Week 2)
  • Program Gap Calculation algorithms.
  • Integrate Claude 3.5 Sonnet API.
🤝 Review Checkpoint
End of Week 2

Review Objectives:

  • Validate extracted data accuracy.
  • Approve gap calculations against COE baseline.
🎯 Official Output
Structured Data & Logic

A programmatic engine converting cultural statements into AI-ready data.

BRD: Structured tables of criteria
2

AI Engine & Consultant Interface

Generating tactics and building the review dashboard
BRD Phase 2: Design
📅 Sprints & Tasks
Sprint 3 (Week 3)
  • Execute API calls to generate Tactics.
  • Build Consultant Dashboard (UI).
  • Develop Inline Editing tool for SMEs.
🤝 Review Checkpoint
End of Week 3

Review Objectives:

  • Evaluate AI "Tone of Voice".
  • Test approval/locking workflow.
🎯 Official Output
Culture Dimension Design

Interactive portal displaying criteria, proposed tactics, and values.

BRD: Culture Dimension Design Doc
3

Reporting Automation & Launch

Exporting official deliverables and final testing
BRD Phase 3: Execution
📅 Sprints & Tasks
Sprint 4 (Week 4)
  • Automated PPTX export engine.
  • Narrative Report (Word) export engine.
Sprint 5 (Week 5)
  • (Buffer) End-to-End (E2E) testing.
  • Process final SME feedback.
🤝 Review Checkpoint
End of Week 5

Review Objectives:

  • Live System Demo (End-to-End).
  • Approve exported artifacts.
🎯 Official Output
Final Export Outputs

Ready-to-present documents generated instantly based on AI analysis.

BRD: Narrative Report & PPTX

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.