> ## Documentation Index
> Fetch the complete documentation index at: https://foundry.awaaz.de/llms.txt
> Use this file to discover all available pages before exploring further.

# problem-statement

***

<Note>
  **Hackathon Date:** January 29, 2026 • 5:00 PM - 9:00 PM IST
</Note>

***

## January 2026: Call Recording Review Portal

### The Problem

Our language consultants review thousands of voice agent recordings daily across Hindi, Marathi, Tamil, Kannada, Spanish, and other languages. Today's workflow is painful:

<Steps>
  <Step title="Log into AWS Console">
    Navigate through IAM authentication
  </Step>

  <Step title="Find S3 Bucket">
    Locate `ad2-production` among dozens of buckets
  </Step>

  <Step title="Construct the Path">
    Manually build path using long UUID: `media/{tenant}/freeswitch/{YYYY}/{MM}/{DD}/{uuid}/`
  </Step>

  <Step title="Download & Play">
    Download file locally, open in audio player
  </Step>

  <Step title="Track in Spreadsheet">
    Record review notes in separate Excel file
  </Step>
</Steps>

**Result:** 5+ minutes of navigation before a single recording is reviewed.

***

### Your Mission

<Info>
  **Build a web-based Call Recording Review Portal that reduces review friction from minutes to seconds.**
</Info>

Consultants should be able to search, play, and rate recordings without ever touching AWS Console.

***

### Technical Context

<AccordionGroup>
  <Accordion title="Recording Storage (S3)">
    **Bucket:** `ad2-production`

    **Path Format:**

    ```
    s3://ad2-production/media/{tenant_id}/freeswitch/{YYYY}/{MM}/{DD}/{call_uuid}/{filename}.wav
    ```

    **Example:**

    ```
    s3://ad2-production/media/ad_0aa3ac/freeswitch/2026/01/20/0000db25-2319-48db-b1b5-a4f2ceeb2f40/ad_response_12118724_1768886079.wav
    ```
  </Accordion>

  <Accordion title="Metadata (PostgreSQL)">
    Call metadata is stored with fields:

    * `call_uuid` — Unique identifier
    * `timestamp` — Call start time
    * `duration` — Call length in seconds
    * `language` — hi, mr, ta, kn, es, etc.
    * `agent_id` — Voice agent identifier
    * `phone_number` — Customer phone
    * `tenant_id` — Client identifier
  </Accordion>

  <Accordion title="Scale">
    | Metric               | Value        |
    | -------------------- | ------------ |
    | Recordings per month | \~10 million |
    | Average duration     | 2 minutes    |
    | Concurrent users     | 100          |
    | Global access        | Required     |
  </Accordion>

  <Accordion title="Deployment">
    * EC2 instance
    * Must be accessible via internet
    * HTTPS required
  </Accordion>
</AccordionGroup>

***

### Requirements

#### P0 — Must Have

<Steps>
  <Step title="Authentication">
    Enable secure username/password login for all users.
  </Step>

  <Step title="Dashboard">
    Provide a central dashboard to review progress and quality trends.
  </Step>

  <Step title="Language-based access control">
    Ensure consultants can access only recordings for their assigned languages.
  </Step>

  <Step title="Search & Filter">
    Allow filtering by date range, language, UUID, and phone number.
  </Step>

  <Step title="Audio Playback">
    Stream call recordings directly in the app without downloads.
  </Step>

  <Step title="Rating System">
    Enable rating of recordings across defined quality dimensions.
  </Step>
</Steps>

#### P1 — Should Have

<Steps>
  <Step title="Notes & Tags">
    Allow users to add comments and categorize recordings using tags.
  </Step>

  <Step title="Enhanced Ratings">
    Support more detailed or multi-dimensional quality ratings.
  </Step>

  <Step title="Advanced Player">
    Add playback speed control, waveform visualization, and keyboard shortcuts.
  </Step>

  <Step title="Role-based Permissions">
    Support Consultant, Lead, and Admin roles with different access levels.
  </Step>
</Steps>

#### P2 — Bonus

<Steps>
  <Step title="AI Evaluation">
    Automatically rate recordings using an LLM-as-judge.
  </Step>

  <Step title="Human vs AI Comparison">
    Display side-by-side comparisons of human and AI-generated ratings.
  </Step>

  <Step title="Export">
    Allow exporting reviews and ratings as CSV or Excel files.
  </Step>

  <Step title="Sharing">
    Generate shareable links for team collaboration and reviews.
  </Step>
</Steps>

***

### User Roles

| Role           | Permissions                                                 |
| -------------- | ----------------------------------------------------------- |
| **Consultant** | View & rate recordings for assigned languages only          |
| **Lead**       | All consultant permissions + view team's work + manage tags |
| **Admin**      | Full access + user management + all languages               |

***

### Suggested Tech Stack

<Tabs>
  <Tab title="Recommended">
    | Layer        | Technology                 |
    | ------------ | -------------------------- |
    | Backend      | Python (Django or FastAPI) |
    | Frontend     | React/Angular              |
    | Database     | PostgreSQL (existing)      |
    | Auth         | Django Auth or JWT         |
    | Audio Player | wavesurfer.js              |
  </Tab>

  <Tab title="Alternatives">
    Teams are free to choose alternatives if justified:

    * **Backend:** Node.js, Go
    * **Frontend:** Vue, Svelte
    * **Auth:** Auth0, Supabase Auth
    * **Audio:** Howler.js, custom HTML5
  </Tab>
</Tabs>

***

### Sample User Stories

<AccordionGroup>
  <Accordion title="Hindi Consultant" icon="user">
    > "I want to see all unrated Hindi calls from yesterday so I can complete my daily review quota."
  </Accordion>

  <Accordion title="Team Lead" icon="user-tie">
    > "I want to filter calls tagged as 'Training Example' to compile onboarding materials."
  </Accordion>

  <Accordion title="Admin" icon="user-shield">
    > "I want to see which consultants have lowest agreement with AI ratings for calibration training."
  </Accordion>

  <Accordion title="Any User" icon="share">
    > "I want to share a particularly good call with my manager via a simple link."
  </Accordion>
</AccordionGroup>

***

## Schedule

| Time    | Activity                           |
| ------- | ---------------------------------- |
| 4:00 PM | Kickoff, problem walkthrough, Q\&A |
| 4:15 PM | Hacking begins 🚀                  |
| 7:45 PM | Code freeze, prep demos            |
| 8:00 PM | Team demos (10 min each)           |
| 8:30 PM | Voting & judging                   |
| 9:00 PM | Winners announced                  |

***

## Teams

<CardGroup cols={3}>
  <Card title="Team 1" icon="users">
    **Members:**

    * Kapil
    * Sandeep
    * Natansh
  </Card>

  <Card title="Team 2" icon="users">
    **Members:**

    * Anurag
    * Harsh
    * Kashvi
  </Card>

  <Card title="Team 3" icon="users">
    **Members:**

    * Nikunj
    * Manasvi
    * Anusha
  </Card>
</CardGroup>

***

## Evaluation Criteria

| Criteria               | Weight | What We're Looking For                  |
| ---------------------- | ------ | --------------------------------------- |
| **Core Functionality** | 40%    | Search, play, rate — working end-to-end |
| **User Experience**    | 20%    | Intuitive, fast, minimal friction       |
| **Code Quality**       | 15%    | Clean, maintainable, documented         |
| **Security**           | 10%    | Auth works, no obvious vulnerabilities  |
| **Performance**        | 10%    | Handles expected load without lag       |
| **Bonus Features**     | 5%     | AI evaluation, dashboard, extras        |

***

## Resources

### Tools Available

* Full access to coding tools including Claude Code
* Any open-source libraries
* AI assistants for code generation

<Warning>
  **Constraint:** Problems are designed to be challenging even with AI assistance. Expect constraints that require real engineering decisions.
</Warning>

***

## FAQ

<AccordionGroup>
  <Accordion title="What if we can't finish everything?">
    Focus on P0 requirements first. A working MVP beats an incomplete feature-rich app. Judges value "it works" over "it almost does everything."
  </Accordion>

  <Accordion title="Can we use AI tools like Claude Code?">
    Yes! All coding tools are allowed. However, the problem is designed with constraints that require real engineering judgment. AI helps but doesn't solve everything.
  </Accordion>

  <Accordion title="What happens to winning solutions?">
    Winning solutions (or the best parts from multiple teams) may be developed further and deployed to production. You might be building something consultants use daily!
  </Accordion>
</AccordionGroup>

***

<Note>
  **Remember:** The best solutions come from understanding the user. Our consultants spend hours every day reviewing calls — build something that makes their work delightful.
</Note>