Definery

Your personal dictionary companion for language learning. Definery helps you discover, save, and master new vocabulary with an intuitive interface and smart quiz features.

This project showcases ScreenStateKit's Three Pillars pattern in a production iOS app with clean architecture and offline-first capability.

---

Screenshots

Coming Soon

---

Features

Home

• Browse random words with pull-to-refresh
• Infinite scroll pagination
• Multi-language support (English, Spanish, French, German, Italian, Portuguese, Chinese)
• Save words to your personal library
• Offline fallback with cached words

Library

• View and manage saved words
• Quick delete functionality
• Detailed word view with meanings and examples

Quiz Mode

• Timed vocabulary challenges
• Multiple choice questions from your library
• Score tracking and progress

---

Tech Stack

Category	Technology
UI	SwiftUI
Persistence	SwiftData
State Management	ScreenStateKit
Concurrency	Swift async/await, Actors
Testing	Swift Testing, swift-snapshot-testing
Time Testing	swift-clocks
CI/CD	GitHub Actions

---

Architecture

Definery follows Clean Architecture with modular frameworks:

┌─────────────────────────────────────────────┐
│              Definery (Main App)            │
│         Composition Root + UI Layer         │
└──────────────┬──────────────────────────────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────────────────┐
│WordAPI │ │WordCache│ │WordCacheInfra     │
│        │ │        │ │(SwiftData)         │
└───┬────┘ └───┬────┘ └─────────┬──────────┘
    │          │                │
    └──────────┴────────────────┘
               │
               ▼
        ┌────────────┐
        │WordFeature │
        │ (Domain)   │
        └────────────┘

Three Pillars Pattern (ScreenStateKit)

Each feature follows the State + ViewStore + View pattern:

┌─────────────────────────────────────────────────────────────────┐
│                           View                                  │
│                        (SwiftUI)                                │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  @State viewState: FeatureViewState                       │  │
│  │  @State viewStore: FeatureViewStore                       │  │
│  │                                                           │  │
│  │  .onShowLoading($viewState.isLoading)                     │  │
│  │  .onShowError($viewState.displayError)                    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────┬───────────────────────────────────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
         ▼                         ▼
┌─────────────────┐      ┌─────────────────────┐
│     State       │◄─────│     ViewStore       │
│ (ScreenState)   │      │ (ScreenActionStore) │
├─────────────────┤      ├─────────────────────┤
│ @Observable     │      │ actor               │
│ @MainActor      │      │                     │
│                 │      │ func binding(state:)│
│ • isLoading     │      │ func receive(action)│
│ • displayError  │      │                     │
│ • domain data   │      │ • Services injected │
└─────────────────┘      │ • ActionLocker      │
                         └─────────────────────┘

Key Patterns:

• Offline-First: Remote with local fallback
• Protocol-Driven: All dependencies injected via protocols
• Actor-Based: Thread-safe ViewModels

---

Getting Started

1. Clone the repository

   git clone https://github.com/anthony1810/Definery.git
   cd Definery

2. Open in Xcode

   open Definery.xcodeproj

3. Resolve packages - Xcode will automatically fetch dependencies

4. Build and run - Select iOS or macOS target

---

Project Structure

Definery/
├── WordFeature/              # Domain layer (models, protocols)
├── WordAPI/                  # API layer (remote loaders, mappers)
├── WordAPITests/
├── WordCache/                # Cache layer (local loader, DTOs)
├── WordCacheTests/
├── WordCacheInfrastructure/  # Infrastructure (SwiftData store)
├── WordCacheInfrastructureTests/
├── Definery/                 # Main app (composition, UI)
└── DefineryTests/

---

Testing

Run tests via Xcode or command line:

# iOS
xcodebuild test -project Definery.xcodeproj -scheme Definery-iOS -testPlan Definery-iOS

# macOS
xcodebuild test -project Definery.xcodeproj -scheme Definery-macOS -testPlan Definery-macOS

Testing Approach:

• TDD with Swift Testing framework
• Memory leak detection on all components
• Snapshot tests for UI verification
• Testable time with swift-clocks

---

Roadmap

Completed

• Domain layer (WordFeature)
• API layer with remote loader
• Cache layer with local fallback
• SwiftData infrastructure
• Composition root
• Home UI with language filter

In Progress

• Library UI (view/delete saved words)

Planned

• Quiz mode with timer
• Word detail view
• Search functionality
• Widget support
• Localization

---

APIs

Purpose	Provider
Random Words	random-word-api
Definitions	Wiktionary API

---

Resources

• ScreenStateKit - State management
• swift-clocks - Testable time
• swift-snapshot-testing - UI snapshots

---

License

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