https://github.com/astrion-studio/farelens
iOS flight deal alert app with iOS 26 @Observable patterns + FastAPI backend
https://github.com/astrion-studio/farelens
fastapi flight-deals ios ios26 python swift swiftui travel
Last synced: about 2 months ago
JSON representation
iOS flight deal alert app with iOS 26 @Observable patterns + FastAPI backend
- Host: GitHub
- URL: https://github.com/astrion-studio/farelens
- Owner: astrion-studio
- License: other
- Created: 2025-10-17T00:42:06.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-27T08:18:20.000Z (7 months ago)
- Last Synced: 2025-11-27T21:38:43.030Z (7 months ago)
- Topics: fastapi, flight-deals, ios, ios26, python, swift, swiftui, travel
- Language: Swift
- Size: 26.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 80
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# FareLens ✈️
> iOS flight deal alert app with iOS 26 @Observable patterns + FastAPI backend
[](https://github.com/astrion-studio/FareLens/actions/workflows/ci.yml)
[](https://github.com/astrion-studio/FareLens/actions/workflows/codeql.yml)
[](https://swift.org)
[](https://www.apple.com/ios/)
[](LICENSE)
FareLens is a modern iOS application that helps travelers discover and track flight deals in real-time. Built with SwiftUI and iOS 26's new `@Observable` macro, it demonstrates cutting-edge iOS development patterns and best practices.
## Features
- **Real-time Flight Deal Alerts** - Get notified when prices drop on your favorite routes
- **Smart Queue System** - Intelligent background processing for deal updates
- **Beautiful UI** - Modern design system with liquid glass aesthetics
- **iOS 26 Patterns** - Built with `@Observable`, `@Bindable`, and `@Environment`
- **Type-Safe Architecture** - Leverages Swift's type system for robust code
- **Comprehensive Testing** - Unit tests with high coverage
## Screenshots
_Coming soon_
## Requirements
- **iOS 17.0+**
- **Xcode 15.0+**
- **Swift 5.9+**
- **macOS 14.0+** (for development)
## Getting Started
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/astrion-studio/FareLens.git
cd FareLens
```
2. **Open in Xcode**
```bash
open ios-app/FareLens.xcodeproj
```
3. **Build and Run**
- Select your target device or simulator
- Press `Cmd + R` to build and run
### Running Tests
```bash
cd ios-app
xcodebuild test -scheme FareLens -destination 'platform=iOS Simulator,name=iPhone 15 Pro'
```
Or use Xcode's Test Navigator (`Cmd + 6`) and click the play button.
## Architecture
FareLens follows a clean, modular architecture:
```
ios-app/FareLens/
├── App/ # App entry point and configuration
├── Core/ # Core utilities, networking, storage
├── Data/ # Data layer (repositories, models)
├── DesignSystem/ # Reusable UI components and theme
├── Features/ # Feature modules (Deals, Alerts, etc.)
└── Resources/ # Assets, localization
```
### Key Architectural Principles
- **iOS 26 @Observable Pattern** - Modern state management without `ObservableObject`
- **Dependency Injection** - Via `@Environment` for testability
- **Repository Pattern** - Abstracted data access layer
- **Smart Queue Service** - Background task processing
- **Type-Safe Networking** - Async/await with structured concurrency
For detailed architecture documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).
## iOS 26 @Observable Patterns
This project uses iOS 26's new observation framework:
```swift
@Observable
final class DealsViewModel {
var deals: [Deal] = []
var isLoading = false
func fetchDeals() async {
isLoading = true
// Automatic UI updates, no @Published needed!
deals = await repository.fetchDeals()
isLoading = false
}
}
```
**Key Differences from ObservableObject:**
- ✅ Use `@Observable` instead of `ObservableObject`
- ✅ Use `@Bindable` for two-way bindings
- ✅ Use `@State` for local state
- ❌ No `@Published` properties
- ❌ No `@StateObject` or `@ObservedObject`
See [iOS_26_PATTERNS.md](iOS_26_PATTERNS.md) for comprehensive examples.
## Code Quality
We maintain high code quality standards:
- **SwiftLint** - Enforces Swift style guidelines
- **SwiftFormat** - Automatic code formatting
- **CI/CD** - Automated checks on every PR
- No force unwraps (`!`) in production code
- No print statements (use OSLog)
- No SwiftUI previews with hardcoded data
- **Code Review** - Automated review via Codex
- **Security Scanning** - Dependabot, secret scanning, CodeQL
### Local Development
```bash
# Format code
swiftformat ios-app/FareLens/
# Lint code
swiftlint lint --path ios-app/FareLens/
# Run tests
xcodebuild test -scheme FareLens -destination 'platform=iOS Simulator,name=iPhone 15 Pro'
```
## Contributing
We welcome contributions! Please follow these guidelines:
1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **Follow code style** - Use SwiftFormat and SwiftLint
4. **Write tests** - Maintain or improve code coverage
5. **Follow iOS 26 patterns** - See [iOS_26_PATTERNS.md](iOS_26_PATTERNS.md)
6. **Commit with conventional commits** - See [Conventional Commits](#conventional-commits)
7. **Open a Pull Request** - Fill out the PR template completely
### Conventional Commits
We use [Conventional Commits](https://www.conventionalcommits.org/) for clear commit history:
```
feat: Add price alert notifications
fix: Resolve deal refresh crash
docs: Update architecture documentation
test: Add tests for SmartQueueService
refactor: Simplify DealsRepository
chore: Update dependencies
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## Documentation
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed architecture overview
- **[iOS_26_PATTERNS.md](iOS_26_PATTERNS.md)** - iOS 26 @Observable patterns
- **[WORKFLOW.md](WORKFLOW.md)** - Development workflow guide
- **[API.md](API.md)** - Backend API documentation
- **[TOOLING_SETUP.md](TOOLING_SETUP.md)** - Development tools setup
- **[GOLDEN_STANDARD_TODO.md](GOLDEN_STANDARD_TODO.md)** - GitHub best practices checklist
## Tech Stack
### iOS App
- **Language**: Swift 5.9+
- **UI Framework**: SwiftUI
- **State Management**: @Observable (iOS 26)
- **Networking**: URLSession + async/await
- **Testing**: XCTest
- **Code Quality**: SwiftLint, SwiftFormat
### Backend (Planned)
- **Framework**: FastAPI (Python)
- **Database**: PostgreSQL
- **Cache**: Redis
- **APIs**: Flight search APIs
## Roadmap
- [x] iOS app core architecture
- [x] Deal listing and detail views
- [x] Smart queue background processing
- [x] Unit tests
- [x] CI/CD pipeline
- [ ] Backend API integration
- [ ] Push notifications
- [ ] Price tracking and alerts
- [ ] User authentication
- [ ] Favorites and saved searches
- [ ] App Store release
## License
Copyright (c) 2024-2025 Astrion Studio. All Rights Reserved.
This is proprietary software. See the [LICENSE](LICENSE) file for details.
**Note:** This repository is temporarily public to utilize free GitHub security features during development. This does NOT grant any rights to use, modify, or distribute the code.
## Acknowledgments
- Built with iOS 26 @Observable patterns
- Inspired by modern flight deal tracking services
- Designed with Apple's Human Interface Guidelines
## Contact
- **GitHub**: [@astrion-studio](https://github.com/astrion-studio)
- **Issues**: [GitHub Issues](https://github.com/astrion-studio/FareLens/issues)
---
**Made with ❤️ by Astrion Studio**