diff --git a/AGENTS.md b/AGENTS.md index 18a9840..61dcc2b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -486,36 +486,12 @@ Color.Primary.background ## Documentation instructions -### Reference documentation before starting work - -Before implementing features or making changes, **always read the following files** for context: - -- **`README.md`**: User-facing documentation with features, usage instructions, and known limitations -- **`AI_IMPLEMENTATION.md`**: Technical implementation guide with architecture patterns, code examples, and troubleshooting - -These files contain important context about existing patterns, workarounds, and design decisions that should inform your implementation. - -### Keep documentation up to date - -- **Always update `README.md`** when adding user-facing features, changing usage patterns, or discovering new limitations. -- **Always update `AI_IMPLEMENTATION.md`** when: - - Adding new architectural patterns or components - - Implementing workarounds for library limitations - - Adding new troubleshooting guidance - - Changing how features are implemented +- **Always keep documentation up to date** when adding new functionality or making changes that users or developers need to know about. - Document new features, settings, or behaviors in the appropriate documentation files. - Update documentation when modifying existing behavior. - Include any configuration options, keyboard shortcuts, or special interactions. - Documentation updates should be part of the same commit as the feature/change they document. -### Documentation checklist - -When completing a task, verify: -- [ ] `README.md` reflects any user-facing changes -- [ ] `AI_IMPLEMENTATION.md` reflects any implementation changes -- [ ] New workarounds or patterns are documented for future reference -- [ ] Known limitations are listed if discovered - ## PR instructions diff --git a/AI_Implementation.md b/AI_Implementation.md new file mode 100644 index 0000000..c3fb67a --- /dev/null +++ b/AI_Implementation.md @@ -0,0 +1,68 @@ +# AI_Implementation.md + +## How This App Was Architected & Built + +This project was developed following strict senior-level iOS engineering standards, with guidance from an AI assistant (Grok) acting as a Senior iOS Engineer specializing in SwiftUI and modern Apple frameworks. + +### Guiding Principles (from AGENTS.md) +- **Protocol-Oriented Programming (POP) first**: All shared capabilities defined via protocols before concrete types +- **MVVM-lite**: Views are "dumb" — all logic lives in `@Observable` view models +- **No third-party dependencies**: Pure Apple frameworks only (SwiftUI, AVFoundation, StoreKit 2, CoreImage) +- **No magic numbers**: All dimensions, opacities, durations from centralized `Design` constants +- **Full accessibility**: Dynamic Type, VoiceOver labels/hints/traits/announcements +- **Modern Swift & SwiftUI**: Swift 6 concurrency, `@MainActor`, `foregroundStyle`, `clipShape(.rect)`, `NavigationStack` +- **Testable & reusable design**: Protocols enable mocking and future SPM package extraction + +### Architecture Overview + +Shared/ +├── DesignConstants.swift → Semantic design tokens (spacing, radii, sizes, etc.) +├── Color+Extensions.swift → Ring light color presets +├── Protocols/ +│ ├── RingLightConfigurable.swift → Border, color, brightness, mirror, smoothing +│ ├── CaptureControlling.swift → Timer, grid, zoom, capture mode +│ └── PremiumManaging.swift → Subscription state & purchase handling +└── Premium/ +└── PremiumManager.swift → Native StoreKit 2 implementation +Features/ +├── Camera/ → Main UI, preview, capture logic +├── Settings/ → Configuration screens +└── Paywall/ → Pro subscription flow + + +### Key Implementation Decisions + +1. **Ring Light Effect** + - Achieved by coloring the safe area background and leaving a centered rectangular window for camera preview + - Border width controlled via user setting + - Gradient support added for directional "portrait lighting" + +2. **Camera System** + - `AVCaptureSession` with front camera default + - `UIViewRepresentable` wrapper for preview with pinch-to-zoom + - Video data output delegate for future real-time filters (skin smoothing placeholder) + +3. **Capture Enhancements** + - Timer with async countdown and accessibility announcements + - Volume button observation via KVO on `AVAudioSession.outputVolume` + - Flash burst: temporarily sets brightness to 1.0 on capture + +4. **Freemium Model** + - Built with pure StoreKit 2 (no RevenueCat) + - `PremiumManaging` protocol enables easy testing/mocking + - Clean paywall with benefit list and native purchase flow + +5. **Reusability Focus** + - All shared logic extracted to protocols + - Ready for future extraction into SPM packages: + - `SelfieCameraKit` + - `SelfieRingLightKit` + - `SelfiePremiumKit` + +### Development Process +- Iterative feature additions guided by competitive analysis of top App Store selfie apps +- Each new capability (timer, boomerang, gradient, subscriptions) added with protocol-first design +- Strict adherence to no magic numbers, full accessibility, and clean separation +- Final structure optimized for maintainability and future library extraction + +This app demonstrates production-quality SwiftUI architecture while delivering a delightful, competitive user experience. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..dec8703 --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# SelfieRingLight + +A modern, professional-grade selfie camera app for iOS that simulates a high-quality ring light using the device's screen. Built entirely with SwiftUI, Swift 6, and AVFoundation. + +Perfect for low-light selfies, video calls, makeup checks, or professional portrait lighting on the go. + +## Features + +### Core Camera & Lighting +- Full-screen front-camera preview with true mirror option +- Configurable **screen-based ring light** with adjustable border thickness +- Multiple color temperature presets (Pure White, Warm Cream, Ice Blue, Rose Pink, etc.) +- **Directional gradient lighting** for flattering portrait effects +- Real-time screen brightness control (overrides system brightness while in use) +- Flash burst on capture for extra fill light + +### Capture Modes +- Photo capture (saved to Photo Library) +- Video recording +- **Boomerang** mode (3-second looping short video) +- 3-second and 10-second self-timer with countdown overlay and VoiceOver announcements +- Pinch-to-zoom gesture +- Volume button shutter support (photo or video start/stop) +- Rule-of-thirds grid overlay (toggleable) + +### Premium Features (Freemium Model) +- All advanced color presets + custom colors +- Gradient and directional lighting +- Advanced beauty filters (coming soon) +- Unlimited boomerang length +- No watermarks +- Ad-free experience + +### Accessibility & Polish +- Full VoiceOver support with meaningful labels, hints, and announcements +- Dynamic Type and ScaledMetric for readable text +- String Catalog localization ready (`.xcstrings`) +- Prevents screen dimming during use +- Restores original brightness on background/app close + +## Screenshots +*(Add App Store-ready screenshots here once built)* + +## Requirements +- iOS 18.0 or later +- Xcode 16+ +- Swift 6 language mode + +## Setup + +### 1. Clone the Repository +```bash +git clone https://github.com/yourusername/SelfieRingLight.git +cd SelfieRingLight +``` + +### 2. Configure API Keys + +This project uses `.xcconfig` files to securely manage API keys. **Never commit your actual API keys to version control.** + +1. Copy the template file: + ```bash + cp SelfieRingLight/Configuration/Secrets.xcconfig.template SelfieRingLight/Configuration/Secrets.xcconfig + ``` + +2. Edit `Secrets.xcconfig` with your actual API key: + ``` + REVENUECAT_API_KEY = appl_your_actual_api_key_here + ``` + +3. The `Secrets.xcconfig` file is gitignored and will never be committed. + +### 3. RevenueCat Setup + +1. Create an account at [RevenueCat](https://www.revenuecat.com) +2. Create a new project and connect it to App Store Connect +3. Create products in App Store Connect (e.g., `com.yourapp.pro.monthly`, `com.yourapp.pro.yearly`) +4. Configure the products in RevenueCat dashboard +5. Create an entitlement named `pro` +6. Create an offering with your subscription packages +7. Copy your **Public App-Specific API Key** to `Secrets.xcconfig` + +### 4. Debug Premium Mode + +To test premium features without a real subscription during development: + +1. Edit Scheme (⌘⇧<) → Run → Arguments +2. Add Environment Variable: + - **Name:** `ENABLE_DEBUG_PREMIUM` + - **Value:** `1` + +This unlocks all premium features in DEBUG builds only. + +### 5. CI/CD Configuration + +For automated builds, set the `REVENUECAT_API_KEY` environment variable in your CI/CD system: + +**GitHub Actions:** +```yaml +env: + REVENUECAT_API_KEY: ${{ secrets.REVENUECAT_API_KEY }} +``` + +**Xcode Cloud:** +Add `REVENUECAT_API_KEY` as a secret in your Xcode Cloud workflow. + +## Privacy +- Camera access required for preview and capture +- Photo Library access required to save photos/videos +- Microphone access required for video recording +- No data collection, no analytics, no tracking + +## Monetization +Freemium model with optional "Pro" subscription: +- Free: Basic ring light, standard colors, photo/video, timer, zoom +- Pro: Full color palette, gradients, advanced features, future updates + +Implemented with RevenueCat for reliable subscription management. + +## Project Structure + +``` +SelfieRingLight/ +├── App/ # App entry point +├── Features/ +│ ├── Camera/ # Camera preview, capture, view model +│ ├── Paywall/ # Pro subscription flow +│ └── Settings/ # Configuration screens +├── Shared/ +│ ├── Configuration/ # xcconfig files (API keys) +│ ├── Premium/ # PremiumManager (RevenueCat) +│ ├── Protocols/ # Shared protocols +│ ├── Color+Extensions.swift # Ring light color presets +│ └── DesignConstants.swift # Design tokens +└── Resources/ # Assets, localization +``` + +## License +*(Add your license here)*