# Core Features

#### Project Management

Projects are the central organizational unit in Pebbl. Each project represents a writing assignment, research topic, or academic work.

**Project Properties**

* **Title**: Short descriptive name (e.g., "Climate Change Essay")
* **Tags**: Comma-separated keywords (e.g., "environment, science, policy")
* **Description**: Optional detailed description
* **Course ID**: Link to a specific course (optional)
* **Linked Lectures**: Associate recorded lectures with projects
* **Creation/Update Timestamps**: Automatic tracking
* **Active Status**: Archive completed projects

**Project Actions**

* **Start Voice Session**: Begin conversational essay development
* **View Draft**: See generated academic drafts
* **Delete Project**: Remove project and associated data
* **Archive**: Mark as inactive (future feature)

#### Voice Sessions & Essay Development

This feature transforms spoken thoughts into structured academic writing through AI-guided conversation.

**Workflow**

1. **Initial Recording**
   * Tap microphone to start recording
   * Speak your initial thoughts on the topic (30 seconds to several minutes)
   * Real-time transcription appears on screen
   * Tap stop when finished
2. **AI Follow-Up Questions**
   * AI analyzes your transcription
   * Generates 3 thoughtful follow-up questions
   * Questions are designed to:
     * Deepen your thinking
     * Clarify ambiguous points
     * Explore counterarguments
     * Add supporting evidence
3. **Response Recording**
   * Select one question to answer
   * Record your response
   * Repeat for additional depth (supports multiple turns)
4. **Draft Generation**
   * Review conversation history
   * Configure draft settings:
     * **Word Goal**: Target length (default 500 words)
     * **Tone**: Neutral, Academic, or Conversational
     * **Refinement Level**: Light Polish, Moderate, or Structured
     * **Include Summary**: Add executive summary
     * **Include Key Takeaways**: Add bullet-point highlights
   * Tap "Generate Draft"
   * AI converts entire conversation into cohesive essay

**Draft Configuration Options**

**Tone Settings**

| Tone               | Description                                     | Best For                      |
| ------------------ | ----------------------------------------------- | ----------------------------- |
| **Neutral**        | Balanced, objective language                    | General writing, reports      |
| **Academic**       | Formal scholarly tone with technical vocabulary | Research papers, theses       |
| **Conversational** | Approachable, friendly style                    | Blog posts, reflective essays |

**Refinement Levels**

| Level            | Description                           | Example Changes                                         |
| ---------------- | ------------------------------------- | ------------------------------------------------------- |
| **Light Polish** | Minimal grammar and flow improvements | Fix typos, basic sentence structure                     |
| **Moderate**     | Improve clarity and structure         | Better transitions, clearer arguments                   |
| **Structured**   | Complete reorganization               | New paragraph structure, topic sentences, strong thesis |

**Data Storage**

* **Voice Streams**: Each exchange stored in `VoiceStreamEntity`
* **Drafts**: Multiple versions stored in `DraftEntity`
* **Version Control**: Previous draft versions preserved

#### Lecture Recording & Analysis

Record lectures with real-time transcription and receive comprehensive AI-generated study materials.

**Recording Process**

1. **Start Lecture Recording**
   * Navigate to "Record Lecture" from main menu
   * Grant microphone permission if not already granted
   * Tap record button
2. **Live Transcription**
   * Real-time speech-to-text using Vosk
   * View transcription as you record
   * See recording duration
   * Visual amplitude feedback shows audio levels
3. **Pause/Resume**
   * Pause recording to skip irrelevant sections
   * Resume seamlessly
   * Total duration tracked
4. **Stop & Process**
   * Tap stop when lecture ends
   * Transcription saved to database
   * AI processing begins automatically

**AI-Generated Outputs**

After recording, Pebbl generates four types of study materials:

**1. Overview**

* **Length**: 10-11 lines
* **Purpose**: High-level summary of topics covered
* **Content**: Main themes, key concepts, important points
* **Use Case**: Quick review before exams

**2. Detailed Notes**

* **Format**: Structured markdown with headings
* **Content**:
  * Key concepts explained
  * Important definitions
  * Connections between ideas
  * Visual hierarchy with bullet points
* **Use Case**: Primary study resource

**3. Comprehensive Summary**

* **Structure**:
  * Clear explanation of each topic
  * "What this means" reflection sections
  * Synthesis of information
* **Use Case**: Deep understanding and exam essays

**4. Flashcards**

* **Format**: Question & Answer pairs
* **Question Types**:
  * Comprehension-based
  * Definition recall
  * Application scenarios
* **Use Case**: Active recall practice

**Technical Details**

* **Transcription**: Offline Vosk model (no internet needed during recording)
* **AI Processing**: Online via OpenRouter API (requires internet)
* **Audio Storage**: Optional audio file saving (future feature)
* **Word Count**: Automatically calculated from transcription

#### Achievement System

Pebbl gamifies learning through a "Pebble" collection system that celebrates milestones.

**Pebble Types**

| Type            | Color                | Description                     | Unlock Condition           |
| --------------- | -------------------- | ------------------------------- | -------------------------- |
| **GROWTH**      | #00A86B (Green)      | First steps in learning journey | Complete first project     |
| **MASTERY**     | #0B1215 (Dark)       | Deep understanding achieved     | Generate 10 drafts         |
| **INSIGHT**     | #FFD700 (Gold)       | Breakthrough moment             | Record lecture over 30 min |
| **CONSISTENCY** | #4169E1 (Royal Blue) | Regular practice                | Use app 7 days in a row    |
| **CREATIVITY**  | #FF69B4 (Pink)       | Unique ideas expressed          | Use conversational tone    |
| **DEPTH**       | #8B4513 (Brown)      | Thorough exploration            | Answer all 3 AI questions  |

**Achievement Display**

* **Recent Pebbles Row**: Shows last 3 achievements on project list
* **Pebble Collection Screen**: Full gallery of locked/unlocked achievements
* **Celebration Dialog**: Animated popup when earning new pebble
* **Total Count**: Track cumulative achievements

**Database Storage**

Achievements stored in `AchievementEntity`:

```kotlin
data class AchievementEntity(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val type: PebbleType,
    val unlockedAt: Long,
    val totalCount: Int = 1
)
```