📱 TikWiki

An immersive, short-form micro-learning mobile application built with Flutter. TikWiki translates the hyper-engaging, vertical-scrolling UI/UX design paradigms of TikTok into an educational ecosystem powered by the Wikipedia knowledge graph and Gemini AI.

---

✨ Features

• TikTok-Style Swipe Feed: Immersive, vertical-scrolling card interface showing quick summaries of Wikipedia articles.
• Interactive Mind Map: Long-press any article card to trigger an interactive, visual mind-map overlay allowing you to jump and navigate to related article nodes.
• Gemini AI Assistant: Built-in chat assistant powered by Firebase AI Logic / Gemini. Summarize, ask questions, or request deep dives directly inside the context of the article.
• Immersive Article Reader: A custom-tailored article reader featuring:
  • Reading progress bar & dynamic Table of Contents (ToC).
  • Configurable typography (font sizing, serif/sans-serif families, line height, and color themes).
  • Find-in-article text search with animated match counts.
  • Media & zoomable image gallery viewer.
• Offline Reading: Batch download articles to local cache via settings or auto-download when saving/liking. Read complete articles offline with auto-prioritized local offline content.
• Deep Linking: Native integration with standard Wikipedia links (*.wikipedia.org/wiki/*) and custom app scheme (tikwiki://wiki) with local notification status updates.
• Recommendation Scoring Engine: Personalization engine that ranks candidates by category interests, user telemetry, and interaction weights.
• Category Spacing & Attenuation: Attenuates repeated categories to maintain topic diversity and avoid user fatigue.
• Activity & Sync: Instant bookmarking, likes, comment threads, and synchronization of user history across devices with Firebase Firestore.
• Guest Mode Protection: Restricts sensitive social actions (liking, bookmarking, commenting, AI chat) to signed-in users with smooth authorization popups.

---

🛠️ Project Architecture Overview

TikWiki uses an isolated, modular local monorepo architecture to strictly decouple the data fetching layer, algorithmic scoring mechanism, and presentation state machines.

Core Directory Blueprint

tikwiki/ (Root Workspace)
├── android/                   # Native Android configuration (Kotlin Gradle DSL)
├── ios/                       # Native iOS configuration
├── lib/                       # Main application shell
│   ├── app.dart               # MaterialApp + router configuration
│   ├── main.dart              # Entry point & Firebase initialization
│   ├── core/                  # Shared DI, router, theme, error utilities
│   └── features/
│       ├── ai/                # Gemini AI chat interface and state
│       ├── auth/              # Clean auth layer (data/domain/presentation)
│       ├── discover/          # Discover feed, swipe controls, reader sheet
│       ├── profile/           # User profile details and activity timeline
│       ├── saved/             # Bookmarks list
│       └── search/            # Wikipedia autocomplete search and results
└── packages/                  # Isolated Monorepo Business & Domain Logic
    ├── wikipedia_api/         # Pure Dart package: Wikipedia API wrapper
    └── tikwiki_algo/          # Pure Dart package: Ranking, Scoring & Filters

---

⚖️ Algorithmic Personalization Layer (tikwiki_algo)

A pure domain-logic module that calculates feed scores and manages state filtering. It filters a candidate pool of WikiSummary structures and builds a deterministic priority feed based on user telemetry.

The 4-Stage Feed Pipeline

graph TD
    A["📥 Candidate Pool Sourcing"] --> B["🧼 Local De-duplication Filter (Seen Ledger)"]
    B --> C["🧮 Parametric Scoring Equation Engine"]
    C --> D["⚖️ Category Diversity Attenuation Selector"]

    style A fill:#1e1e2e,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style B fill:#1e1e2e,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style C fill:#1e1e2e,stroke:#313244,stroke-width:2px,color:#cdd6f4
    style D fill:#1e1e2e,stroke:#313244,stroke-width:2px,color:#cdd6f4

Loading

The Interaction Scoring Formula

$$\text{Score} = (W_{\text{like}} \cdot \text{Likes}) + (W_{\text{comm}} \cdot \text{Comments}) + (W_{\text{save}} \cdot \text{Saves}) - (W_{\text{down}} \cdot \text{Downvotes})$$

Factor / Interaction	Weight	Impact	Description
Like ($W_{\text{like}}$)	+1	Positive	Basic approval indicator
Comment Open ($W_{\text{comm}}$)	+4	Positive	Engagement signal (opening comment sections)
Bookmark / Save ($W_{\text{save}}$)	+8	Positive	Strongest positive interest signal (saving to reading lists)
Downvote / Skip ($W_{\text{down}}$)	-10	Negative	Harsh penalty for explicit downvotes or rapid swipes (<3s)

---

🚀 Workspace Setup & Commands

Automation scripts and Makefile targets are provided to configure, build, and run dependencies uniformly:

# One-shot developer environment setup (FVM + Flutter + iOS Pods + Mason)
make setup

# Run build_runner code generation
make gen

# Run formatting and analysis
make format
make analyze

# Run unit and widget tests
make test

# Run application in debug mode
make run

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.