# Architecture Overview

## System Diagram

```mermaid
graph TB
    TG[Telegram Mini-App] --> API[Bot API Gateway]
    API --> AUTH[Auth Service]
    API --> AI[AI Scorer Service]
    API --> CHAIN[Blockchain Layer]
    
    AUTH --> VERIFY[initData Verification]
    AI --> VECTOR[Vector Database]
    AI --> FACTS[Fact-Check Engine]
    CHAIN --> IPFS[IPFS Storage]
    CHAIN --> TOKEN[Token Contract]
    
    VECTOR --> EMBED[Embedding Model]
    FACTS --> KNOWLEDGE[Knowledge Base]
    IPFS --> HASH[Content Hash]
    TOKEN --> MINT[Mint & Transfer]
```

## Core Components

### 1. 📱 Telegram WebApp Layer

**Client-Side (React/TypeScript)**

```javascript
// Secure initData verification
const { initData, user } = WebApp.initDataUnsafe;

// Submit idea with encryption
const submitIdea = async (content) => {
  const encrypted = await encryptContent(content);
  return api.post('/submit', { 
    content: encrypted,
    initData,
    timestamp: Date.now()
  });
};
```

**Core Creativity Elements:**

* Telegram WebApp SDK integration
* Client-side encryption
* Offline draft storage
* Progressive Web App capabilities

### 2. 🤖 Bot API Gateway

**Backend (Node.js/Express)**

```javascript
// Telegram auth verification
app.post('/api/auth/telegram', async (req, res) => {
  const { initData } = req.body;
  
  if (verifyTelegramWebAppData(initData)) {
    const user = parseInitData(initData);
    const token = jwt.sign({ user }, JWT_SECRET);
    res.json({ token, user });
  } else {
    res.status(401).json({ error: 'Invalid auth' });
  }
});
```

**Responsibilities:**

* Authentication & authorization
* Request routing & validation
* Rate limiting & abuse prevention
* Real-time updates via WebSocket

### 3. 🤖 Robot Creativity Scorer

**Processing Pipeline:**

```python
# Simplified scoring pipeline
class CreativityScorer:
    def score_idea(self, content: str) -> Score:
        # 1. Vectorize content
        vector = self.embedding_model.encode(content)
        
        # 2. Check originality
        originality = self.check_originality(vector)
        
        # 3. Fact-check content
        factual_score = self.fact_checker.verify(content)
        
        # 4. Calculate final score
        final_score = self.calculate_composite_score(
            originality, factual_score, complexity, innovation
        )
        
        return Score(
            total=final_score,
            originality=originality,
            factual=factual_score,
            reward_tokens=self.calculate_reward(final_score)
        )
```

**Robot Intelligence Components:**

* **Embedding Model**: Converts dedicated ideas to semantic vectors
* **Similarity Engine**: Compares against existing creativity offerings
* **Fact-Check API**: Verifies claims against knowledge base
* **Scoring Algorithm**: Composite creativity evaluation

### 4. ⛓️ Blockchain Layer

**Smart Contract (Solidity)**

```solidity
// Simplified idea submission contract
contract AltarOfCreativity {
    struct Idea {
        address creator;
        string ipfsHash;
        uint256 score;
        uint256 timestamp;
        uint256 reward;
    }
    
    mapping(uint256 => Idea) public ideas;
    uint256 public ideaCount;
    
    function submitIdea(
        string memory ipfsHash,
        uint256 score
    ) external {
        ideas[ideaCount] = Idea({
            creator: msg.sender,
            ipfsHash: ipfsHash,
            score: score,
            timestamp: block.timestamp,
            reward: calculateReward(score)
        });
        
        // Mint reward tokens
        _mint(msg.sender, calculateReward(score));
        
        emit IdeaSubmitted(ideaCount, msg.sender, score);
        ideaCount++;
    }
}
```

**On-Chain Operations:**

* **IPFS Storage**: Decentralized content storage
* **Token Minting**: Automatic reward distribution
* **Leaderboard**: Immutable ranking system
* **Governance**: Future DAO voting mechanisms

## Data Flow

**1. Submission Journey:**

```
Creative Offering → Encrypt → API Gateway → Robot Scorer → Blockchain
```

**2. Scoring Process:**

```
Raw Text → Vectorize → Compare → Verify → Score → Reward
```

**3. Reward Distribution:**

```
Score → Calculate Tokens → Mint → Transfer → Update Leaderboard
```

## Security Measures

**Authentication:**

* Telegram initData verification
* JWT token-based sessions
* Rate limiting per user
* IP-based abuse prevention

**Data Protection:**

* Client-side encryption
* Secure API communication (HTTPS)
* Private credential management
* IPFS content hashing

**Smart Contract Security:**

* Audit by reputable firms
* Multi-signature wallet controls
* Upgrade mechanisms
* Emergency pause functionality

## Performance Metrics

**Target Latencies:**

* Auth verification: <100ms
* Robot creativity scoring: <2 minutes
* Blockchain confirmation: <30 seconds
* Total offering experience: <3 minutes

**Scalability:**

* Horizontal API scaling
* AI worker pool management
* Blockchain batch processing
* CDN for static assets

## Development Environment

**Local Setup:**

```bash
# Clone repository
git clone https://github.com/altar-of-creativity/miniapp

# Install dependencies
npm install

# Start development server
npm run dev:miniapp

# Run local blockchain
npm run dev:blockchain
```

**Technology Stack:**

* **Frontend**: React, TypeScript, Tailwind CSS
* **Backend**: Node.js, Express, PostgreSQL
* **AI**: Python, TensorFlow, Hugging Face
* **Blockchain**: Ethereum, Hardhat, IPFS
* **Deployment**: Vercel, Railway, Infura

***

**Next Steps:**

* [Understand Tokenomics →](https://project-49.gitbook.io/alter-of-creativity/token-primer)
* [View Development Roadmap →](https://project-49.gitbook.io/alter-of-creativity/roadmap)
* [Start Contributing →](https://project-49.gitbook.io/alter-of-creativity/contributing)