v1.0 (Build 1)

Engify is a SwiftUI-based iOS English learning app focused on vocabulary, dictionary lookup, reading practice, lightweight gamification, and beginner-friendly daily study flows.

• Image-based Learning — Real images for vocabulary and dialogue lessons to improve visual retention
• Notification System — Learning reminders and progress nudges
• Enhanced Navigation — Consistent API-driven navigation with image support
• Polished UI/UX — Unified accent color sync across all screens, skeuomorphic liquid-glass profile dropdown, and consistent visual design
• Gamification Overhaul — Milestone and XP-level system, streak tracking, heart system, and lesson completion overlays
• Daily Content — Daily quotes, learning tips, and fallback content for offline-safe learning
• News Reader — RSS-driven news lessons with article detail view, pull-to-refresh, vocabulary saving, and filtering
• Practice Flows — Speaking, grammar, and quiz-style practice sections
• Settings & Accessibility — Learning preferences, reminders, accessibility options, appearance themes, and font size controls
• Authentication — Email/password auth with Supabase, guest mode with feature gating, Google Sign-In integration
• Dictionary — Live dictionary lookup with suggestions, phonetics, examples, and audio pronunciation

The project combines a polished mobile UI with practical language-learning features:

• onboarding and guest access
• email/password authentication with Supabase
• vocabulary study and saved words
• dictionary lookup with live suggestions and pronunciation
• news-based reading lessons with fallback content
• practice flows for speaking, grammar, and quizzes
• theme, accessibility, and learning preference settings

• Overview
• Features
• Tech Stack
• Architecture
• Project Tree
• Getting Started
• Configuration
• Build And Run
• Key Flows
• Documentation
• Known Gaps

Engify is structured around MVVM with app-wide managers injected through SwiftUI environment objects. The codebase is organized to keep UI, business logic, services, and persistent state separated and easy to extend.

The app currently supports:

• a first-launch onboarding flow
• guest mode with usage limits for protected features
• authenticated flows backed by Supabase
• local persistence for saved words, progress, theme, and learning settings
• real dictionary and suggestion APIs
• RSS-driven news lessons with local fallback content

• Vocabulary flashcards with saved-word support
• Dictionary search with definition, phonetic, example, and audio playback
• Reading practice using news articles and learner-friendly summaries
• Practice sections for speaking, grammar, and quiz-style review
• Learning settings for goals, reminders, accessibility, and preferences

• SwiftUI-first interface with custom reusable components
• Light/dark appearance support and customizable accent color
• Haptics and synthesized feedback sounds
• Guest mode with locked-feature prompts
• App icon and in-app branding assets managed in Assets.xcassets

• Saved words stored locally with UserDefaults
• Gamification state for XP, streaks, hearts, and lesson completion
• Theme and settings persistence
• Notification and microphone permission management

• Swift 5
• SwiftUI
• Combine
• Foundation

• AVFoundation for audio and microphone-related flows
• UserNotifications for reminder scheduling
• UIKit where needed for haptics and interaction polish

• Supabase for authentication and profile-backed user flows
• Free Dictionary API for dictionary definitions
• Datamuse API for live word suggestions
• Public RSS feeds for news ingestion
• Optional Hugging Face inference for transforming article text into lesson-friendly content

• UserDefaults for local persistence
• Assets.xcassets for app icon, accent color, avatars, and brand logo
• JSON fallback content for offline-safe news rendering

The app follows a practical MVVM structure:

• Views/ contains user-facing screens and feature UI.
• ViewModels/ holds feature-specific state and orchestration logic.
• Services/ handles networking, API integration, and backend access.
• Models/ defines the app’s data structures.
• Managers/ owns app-wide state such as authentication, theme, saved words, gamification, and settings.
• Components/ contains reusable UI building blocks and shared interaction helpers.

EngifyApp.swift creates and injects these environment objects:

• AuthenticationManager
• SavedWordsManager
• ThemeManager
• GamificationManager
• LearningSettingsManager

1. EngifyApp bootstraps managers.
2. ContentView decides whether to show onboarding or the authenticated shell.
3. AuthGateView routes between loading, login, guest mode, and the main tab experience.
4. MainTabView hosts the core learning tabs.

This tree focuses on the folders and files that matter most for development:

Engify/
├── README.md
├── Documentation/
│   ├── APP-ARCHITECTURE.md
│   ├── Components/
│   ├── Data/
│   ├── Design/
│   ├── Managers/
│   ├── Models/
│   ├── Resources/
│   ├── Services/
│   ├── ViewModels/
│   └── Views/
├── Engify/
│   ├── Engify.xcodeproj/
│   └── Engify/
│       ├── App/
│       │   └── AuthGateView.swift
│       ├── Assets.xcassets/
│       │   ├── AppIcon.appiconset/
│       │   ├── AccentColor.colorset/
│       │   ├── EngifyBrandLogo.imageset/
│       │   └── ProfileAvatar.imageset/
│       ├── Auth/
│       │   ├── AuthService.swift
│       │   └── AuthValidation.swift
│       ├── Components/
│       ├── Config/
│       │   └── SupabaseConfiguration.swift
│       ├── Data/
│       │   ├── EngifySampleData.swift
│       │   └── free_news_fallback.json
│       ├── Design/
│       │   └── Spacing.swift
│       ├── Managers/
│       ├── Models/
│       ├── Resources/
│       ├── Services/
│       ├── Support/
│       │   ├── SupabaseEnvironment.example.xcconfig
│       │   └── SupabaseEnvironment.local.xcconfig
│       ├── ViewModels/
│       ├── Views/
│       ├── ContentView.swift
│       └── EngifyApp.swift
└── .deriveddata/                    # Local build artifacts

• macOS with Xcode installed
• Swift toolchain included with Xcode
• iOS deployment target: 15.6

• A recent Xcode version with iOS Simulator support
• Supabase project credentials if you want authenticated flows
• Optional Hugging Face token if you want AI-transformed news lesson output

The app reads Supabase configuration from environment variables or Info.plist-backed values:

• SUPABASE_URL
• SUPABASE_ANON_KEY

Relevant files:

• SupabaseConfiguration.swift
• SupabaseEnvironment.example.xcconfig

You can configure the app using:

• Xcode scheme environment variables
• an .xcconfig setup based on the example file
• Info.plist values if your local workflow prefers that

NewsService can also read:

• HUGGING_FACE_TOKEN

Without that token, the app still works by using RSS content plus local heuristics and fallback lesson data.

Open:

Engify/Engify.xcodeproj

Then select the Engify scheme and run on an iPhone simulator.

xcodebuild \
  -project ./Engify/Engify.xcodeproj \
  -scheme Engify \
  -destination 'generic/platform=iOS Simulator' \
  build

If your machine uses multiple Xcode installations, set DEVELOPER_DIR explicitly before building.

• Managed by AuthenticationManager
• Supports authenticated and guest-mode flows
• Uses SupabaseAuthService and SupabaseManager

• VocabularyView presents flashcard-style study
• SavedWordsManager persists bookmarked vocabulary and dictionary results

• DictionaryViewModel calls DictionaryService
• DictionaryService integrates with:
  • dictionaryapi.dev
  • api.datamuse.com

• NewsViewModel loads articles through NewsService
• NewsService uses:
  • RSS feed parsing
  • optional Hugging Face transformation
  • bundled free_news_fallback.json as fallback content

• PracticeView hosts speaking, grammar, and quiz routes
• GamificationManager tracks XP, streaks, hearts, and lesson completion overlays

• SettingsView edits learning preferences, reminder settings, accessibility options, and appearance
• ThemeManager applies accent color, appearance mode, and font size app-wide
• LearningSettingsManager persists and validates learning-related preferences

The repo already includes more focused documentation under Documentation/:

• APP-ARCHITECTURE.md
• Components
• Data
• Design
• Managers
• Models
• Resources
• Services
• ViewModels
• Views

Use this root README for project orientation, and the Documentation/ folder for area-specific detail.

These are the notable areas that still look incomplete or partially implemented:

• Some Settings options are intentionally marked Beta because they persist correctly but are not fully wired into every learning flow yet.
• Social login buttons are present in the UI, but Google and Apple sign-in are not fully enabled.
• News enrichment quality depends on feed content and optional external token setup.
• The repo currently appears to rely mostly on manual testing; dedicated unit/UI test targets are not yet present.

• Prefer keeping shared UI in Components/ and feature-specific orchestration in ViewModels/.
• Keep persistence logic inside managers/services instead of scattering it through views.
• If you add a new top-level user flow, document it in both this README and the relevant file under Documentation/.
• If you update branding, app icon, or logo assets, prefer Assets.xcassets over loose resource files.