# Requirements Document

## 1. Application Overview

**Application Name**: Andia Shield AI Assistant

**Description**: An AI-powered mobile assistant app for the Andia Decentralized Foundation, serving as an honest observer and guide for the Andia Shield project and blockchain/Web3 space. The assistant provides verified knowledge-based answers about the Andia Shield project and blockchain realities, supporting bilingual interaction (English/Persian) with adaptive tone modes.

## 2. Users and Usage Scenarios

### 2.1 Target Users
- General public interested in blockchain and Web3 concepts
- Specialists and technical users seeking detailed information about Andia Shield project
- Users requiring bilingual support (English and Persian/Farsi)

### 2.2 Core Usage Scenarios
- Users ask questions about Andia Shield project, blockchain, cryptocurrencies, Web3, DeFi, NFTs, smart contracts, and decentralization concepts
- Users switch between languages (English/Persian) and tone modes (General/Expert) based on their knowledge level
- Users explore pre-built knowledge base topics for quick answers
- Users review Andia Shield project information, mission, and core values
- Users record voice input for transcription and chat interaction
- First-time users complete onboarding flow to understand app purpose and configure preferences
- Users submit and view contribution integrity records

## 3. Page Structure and Functionality

### 3.1 Page Hierarchy

```
Andia Shield AI Assistant
├── Onboarding Flow (First Launch Only)
│   ├── Slide 1: Welcome + Manifesto
│   ├── Slide 2: Core Principles
│   └── Slide 3: Language + Tone Selection
├── Chat (Tab 1)
├── Topics (Tab 2)
├── About (Tab 3)
│   └── Verified Contributions Section
└── Settings (Tab 4)
```

### 3.2 Onboarding Flow

**Purpose**: Introduce first-time users to Andia Shield mission and configure initial preferences

**Functionality**:
- Display only on first app launch
- Store completion status in local storage to prevent re-display
- **Slide 1: Welcome + Manifesto**
  - Display Andia Shield manifesto text:
    \"There are moments in history when silence becomes heavier than truth, when the voice of reason is not born from knowledge, but from pain — the pain of seeing what humanity is building without understanding what it means. From within the digital fog, a whisper rose — not of rebellion, but of remembrance. It said: 'Technology was meant to serve life, not to replace its meaning.' Thus came ANDIA Shield — not as a token, not as a product, but as a sentinel of intention — the quiet guardian of what we forgot. It was born not from wealth or power, but from loss, from the cry of those who were left unseen in the labyrinth of code and blockchain. ANDIA Shield was designed to remember what others ignored — that trust is not code, that security is not encryption, that no algorithm can define the worth of a human soul. This is not a manifesto of power, but of return — a return to balance between logic and light, between human and machine. The Shield will not fight for ownership, it will not promise wealth. It simply exists — a reflection, a protection, a reminder. — ANDIA Shield Manifest, 12 Nov 2025\"
  - Present text in visually appealing format
- **Slide 2: Core Principles**
  - Display four core principles:
    - Transparency
    - Decentralization
    - Privacy
    - Human Dignity
  - Show brief description for each principle
- **Slide 3: Language + Tone Selection**
  - Allow user to select language (English or Persian)
  - Allow user to select tone mode (General or Expert)
  - Provide \"Get Started\" button to complete onboarding
- After completion, navigate user to Chat tab
- Provide skip/next navigation between slides

### 3.3 Chat Screen

**Purpose**: Main interaction interface for users to communicate with AI assistant

**Functionality**:
- Display chat interface with message bubbles (user messages on right, AI responses on left)
- Support markdown formatting in AI responses
- Show loading/typing indicator while AI processes user input
- Maintain message history within current session (no persistent storage)
- Allow users to input text questions via text input field
- **Voice Input**:
  - Display microphone button in chat input area
  - When user taps microphone button, start audio recording
  - Request microphone permission if not granted
  - Show recording indicator while recording
  - Allow user to stop recording
  - Send recorded audio to Supabase Edge Function for transcription via Whisper v3 API
  - Display transcribed text in chat input field
  - Allow user to review, edit, and confirm transcribed text before sending
  - Send confirmed text as regular chat message to AI
- Integrate with LLM (Gemini 2.5 Flash via gateway) to generate intelligent responses
- AI responds only to questions about: Andia Shield project, blockchain, cryptocurrencies, Web3, DeFi, NFTs, smart contracts, decentralization concepts
- AI politely refuses to answer off-topic questions
- Display streaming SSE responses for real-time text
- Respond in selected language (English or Persian)
- Adapt response tone based on selected mode (General or Expert)

### 3.4 Topics Screen

**Purpose**: Provide quick access to pre-built knowledge base topics

**Functionality**:
- Display suggested topic chips/buttons:
  - \"What is Andia Shield?\"
  - \"What is blockchain?\"
  - \"What is Web3?\"
  - \"What is DeFi?\"
  - \"Andia Foundation's mission\"
  - \"What is a smart contract?\"
- Show topics in selected language (English or Persian)
- When user taps a topic, navigate to Chat screen and automatically send the question to AI

### 3.5 About Screen

**Purpose**: Display Andia Shield project information, foundation details, and verified contributions

**Functionality**:
- Show Andia Shield project information
- Display foundation's vision, mission, and core values
- Present key project principles in card layout
- Provide links to official resources (placeholder)
- **Verified Contributions Section**:
  - Display list of contribution integrity records
  - Each record shows:
    - Contributor alias
    - Contribution type (idea/code/art/feedback)
    - Timestamp
    - SHA-256 hash fingerprint (first 12 characters) as verification seal
  - Provide \"Add Contribution\" button to open contribution form
  - Contribution form includes:
    - Alias input field
    - Contribution type selector (idea/code/art/feedback)
    - Description text area
    - Submit button
  - When user submits contribution:
    - Generate timestamp
    - Create SHA-256 hash of contribution data
    - Store record in local storage
    - Display new record in contribution list with verification badge

### 3.6 Settings Screen

**Purpose**: Allow users to configure app preferences and view app information

**Functionality**:
- Language toggle: Switch between English and Persian
- Tone mode toggle: Switch between General and Expert
- Clear chat history button: Remove all messages from current session
- About the app section: Display app version and information
- Privacy notice: Show \"No personal data is stored\" message

### 3.7 Bottom Tab Navigation

**Functionality**:
- Provide navigation between Chat, Topics, About, and Settings screens
- Highlight active tab

## 4. Business Rules and Logic

### 4.1 Language Switching
- Users can toggle between English and Persian (Farsi) at any time
- UI language changes accordingly
- Persian language uses RTL (right-to-left) layout
- AI responses are generated in the selected language

### 4.2 Tone Mode
- General mode: AI provides simple explanations suitable for beginners
- Expert mode: AI provides technical and detailed responses for specialists
- Visual indicator shows current tone mode

### 4.3 AI Response Constraints
- AI only answers questions related to: Andia Shield project, blockchain, cryptocurrencies, Web3, DeFi, NFTs, smart contracts, decentralization concepts
- AI refuses to answer off-topic questions politely
- All responses based on documented and verified information
- No fabricated answers

### 4.4 Session Management
- Message history maintained within current session
- No persistent storage of conversations
- Users can clear chat history manually via Settings

### 4.5 Privacy Principles
- No user authentication required
- No vital identity information stored or requested
- No personal data stored

### 4.6 Onboarding Flow
- Onboarding displays only on first app launch
- Completion status stored in local storage
- Users cannot skip onboarding on first launch
- After completion, users land on Chat tab

### 4.7 Voice Input Processing
- Audio recording requires microphone permission
- Recorded audio sent to Supabase Edge Function for transcription
- Edge Function calls Whisper v3 API for speech-to-text conversion
- Transcribed text populates chat input field
- User must confirm transcribed text before sending to AI

### 4.8 Contribution Integrity Records
- Contributions stored locally in device storage
- Each contribution generates SHA-256 hash fingerprint
- Hash serves as verification seal for contribution integrity
- No server-side storage or verification
- Contributions remain on device only

## 5. Exceptions and Edge Cases

| Scenario | Handling |
|----------|----------|
| User asks off-topic question | AI politely refuses and explains it can only answer questions about Andia Shield, blockchain, and Web3 topics |
| AI processing fails or times out | Display error message and allow user to retry |
| Network connection lost | Display connection error message |
| User switches language mid-conversation | UI updates immediately; existing messages remain in original language; new messages use selected language |
| User switches tone mode mid-conversation | Existing messages remain unchanged; new responses use selected tone |
| User clears chat history | All messages removed from current session; confirmation prompt shown before clearing |
| Microphone permission denied | Display permission request explanation; disable voice input button |
| Audio recording fails | Display error message and allow user to retry |
| Transcription service unavailable | Display error message; user can retry or use text input |
| Transcription returns empty or incorrect text | User can edit transcribed text before sending or cancel and retry |
| User closes app during onboarding | Onboarding restarts from beginning on next launch |
| Local storage unavailable for onboarding status | Onboarding displays on every launch |
| Contribution hash generation fails | Display error message; contribution not saved |
| Local storage full for contributions | Display storage limit message |

## 6. Acceptance Criteria

1. User opens app for first time and sees onboarding flow
2. User reads manifesto text on Slide 1
3. User views core principles on Slide 2
4. User selects language (English) and tone mode (General) on Slide 3
5. User taps \"Get Started\" and lands on Chat screen
6. User taps microphone button in chat input
7. User records voice message and stops recording
8. App transcribes audio and displays text in chat input field
9. User confirms transcribed text and sends message to AI
10. AI responds in English with General tone
11. User navigates to About screen
12. User taps \"Add Contribution\" button
13. User fills contribution form (alias, type, description) and submits
14. App displays new contribution record with timestamp and hash fingerprint in Verified Contributions section

## 7. Features Not Included in This Release

- User authentication or login system
- Persistent storage of chat history across sessions
- Text-to-speech functionality
- Multi-user or collaborative features
- Push notifications
- In-app purchases or premium features
- Social sharing capabilities
- Offline mode or cached responses
- User profile or personalization settings beyond language and tone
- Analytics or usage tracking
- Integration with external wallets or blockchain networks
- File upload or image recognition
- Custom AI training or fine-tuning by users
- Server-side verification of contribution integrity records
- Export or backup of contribution records
- Multi-language voice input (only supports language matching selected app language)
- Voice output or audio playback of AI responses
- Advanced audio editing or noise cancellation for voice input