# artlens-turn-every-frame-into-fine-art/artlens-frontend architecture

> Architecture diagram of the GitHub repository artlens-turn-every-frame-into-fine-art/artlens-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artlens-turn-every-frame-into-fine-art/artlens-frontend
- Repository: https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend

## Overview

1. ArtLens is a React Native mobile app built with Expo and Expo Router. The runtime is organized around file-based navigation in `app/`, with separate tabbed areas for camera, gallery, home, styles, and settings, plus dedicated flow screens for editing, refinement, background generation, export, and sharing.

2. The app’s main architecture is split into three layers: screen/navigation composition in `app/`, domain logic in `core/` and `features/`, and shared state/UI/utilities in `shared/`. This separation suggests the screens stay thin while most ML, hardware, and job orchestration lives outside the route files.

3. Real-time camera processing is centered in `core/camera/useFrameProcessor.ts` and `core/inference/InferenceEngine.ts`. The camera tab likely captures frames through Vision Camera, feeds them into inference, and uses the result for live style-transfer and segmentation-driven rendering.

4. The inference subsystem is designed for performance and device constraints. `core/inference/TiledInferenceRunner.ts` implies large images or frames are processed in tiles to control memory use and maintain responsiveness, while `core/storage/ModelManager.ts` handles model availability and loading.

5. Hardware adaptation is a first-class concern. `core/hardware/HardwareProfiler.ts` and shared stores for hardware and battery state indicate the app adjusts its behavior based on device capability and power conditions, likely influencing frame rate, model choice, or whether certain effects are enabled.

6. Rendering is split from inference. `features/canvas/SkiaRenderer.ts` indicates Skia is used to compose the final visual output, while `shared/ui/ImageCompareSlider.tsx` supports before/after inspection in editing or refinement flows. This keeps ML output generation separate from on-device presentation.

7. User-driven style work is modeled as jobs. `features/style-transfer/StyleJobService.ts` and `shared/stores/useStyleJobStore.ts` suggest an asynchronous pipeline for launching, tracking, and persisting style-transfer tasks across screens such as edit, refine, and export.

8. Background generation is a separate capability from local style transfer. The README and `app/(screens)/background-generator.tsx` indicate the app calls an external generative service through `services/api.ts`, likely sending prompts and receiving generated backgrounds that are then combined with foreground segmentation results.

9. Image intake is unified through `services/useIncomingImage.ts` and `features/upload/hooks/useImageSelection.ts`. These modules appear to normalize images arriving from gallery picks, shares, or other entry points before handing them into the editing pipeline. The dedicated tests around `useIncomingImage` show this is a critical boundary with bug-prone edge cases.

10. Shared state is implemented with lightweight stores in `shared/stores/`, including battery, hardware profile, model, and style-job state. This suggests screen-to-screen coordination happens via global client state rather than a centralized server session, which fits an offline-capable, device-centric mobile app.

11. `context/ContactContext.tsx` and `app/(screens)/about-contact.tsx` represent a small auxiliary subsystem for user contact or support-related data, separate from the core ML workflow.

12. The repository also includes CI/CD and release automation via GitHub Actions in `.github/workflows/`, likely tied to EAS/Expo build and deployment for dev and prod channels. That matters architecturally because the app is shipped as a mobile build pipeline rather than as a web deployment.

13. Overall data flow: image or camera frame enters from the camera/gallery/share surfaces, is normalized by incoming-image and selection services, processed by hardware-aware inference and model management, rendered through Skia/canvas, optionally refined with background generation, and finally exported or shared from the corresponding screens.

Main entry points: [`app/(screens)`](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/tree/main/app/(screens)) (Task screens), [`app/(screens)/edit-canvas.tsx`](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/edit-canvas.tsx) (Edit canvas), [`core/inference/InferenceEngine.ts`](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/inference/InferenceEngine.ts) (Inference engine), [`app/(screens)/refine.tsx`](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/refine.tsx) (Refine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_layout["Router shell<br/>expo-router layout<br/>[_layout.tsx]"]
  node_app_tabs["Tab routes<br/>navigation tabs"]
  node_app_screens["Task screens<br/>route screens"]
  node_camera_tab["Camera<br/>[camera.tsx]"]
  node_gallery_tab["Gallery<br/>[gallery.tsx]"]
  node_edit_canvas["Edit canvas<br/>edit flow<br/>[edit-canvas.tsx]"]
  node_refine_screen["Refine<br/>[refine.tsx]"]
  node_bg_generator["Background gen<br/>generation flow"]
  node_export_screen["Export<br/>output flow<br/>[export.tsx]"]
end

subgraph group_core["Core engine"]
  node_frame_processor["Frame processor<br/>vision camera"]
  node_inference_engine["Inference engine<br/>ml runtime<br/>[InferenceEngine.ts]"]
  node_tiled_runner["Tiled runner<br/>tiling inference"]
  node_model_manager[("Model manager<br/>model storage<br/>[ModelManager.ts]")]
  node_hardware_profiler["Hardware profile<br/>device profiling"]
end

subgraph group_features["Feature services"]
  node_skia_renderer["Skia renderer<br/>rendering<br/>[SkiaRenderer.ts]"]
  node_style_jobs["Style jobs<br/>async jobs<br/>[StyleJobService.ts]"]
  node_image_selection["Image select<br/>upload intake"]
  node_battery_guard["Battery guard<br/>power control<br/>[useBatteryGuard.ts]"]
end

subgraph group_shared["Shared layer"]
  node_battery_store[("Battery store<br/>global state<br/>[useBatteryStore.ts]")]
  node_hardware_store[("Hardware store<br/>global state")]
  node_model_store[("Model store<br/>global state<br/>[useModelStore.ts]")]
  node_style_job_store[("Job store<br/>global state")]
  node_image_compare["Compare slider<br/>ui component"]
end

subgraph group_integration["External integration"]
  node_incoming_image["Incoming image<br/>input normalization"]
  node_api_service["API service<br/>remote api<br/>[api.ts]"]
  node_contact_ctx["Contact context<br/>support context<br/>[ContactContext.tsx]"]
end

node_app_layout -->|"routes"| node_app_tabs
node_app_layout -->|"routes"| node_app_screens
node_app_tabs -->|"entry"| node_camera_tab
node_app_tabs -->|"entry"| node_gallery_tab
node_app_screens -->|"flow"| node_edit_canvas
node_app_screens -->|"flow"| node_refine_screen
node_app_screens -->|"flow"| node_bg_generator
node_app_screens -->|"flow"| node_export_screen
node_camera_tab -->|"frames"| node_frame_processor
node_frame_processor -->|"infer"| node_inference_engine
node_inference_engine -->|"tile"| node_tiled_runner
node_inference_engine -->|"load"| node_model_manager
node_inference_engine -->|"adapt"| node_hardware_profiler
node_hardware_profiler -->|"persist"| node_hardware_store
node_battery_guard -->|"read"| node_battery_store
node_battery_guard -->|"throttle"| node_inference_engine
node_gallery_tab -->|"ingest"| node_incoming_image
node_incoming_image -->|"select"| node_image_selection
node_incoming_image -->|"open"| node_edit_canvas
node_edit_canvas -->|"render"| node_skia_renderer
node_edit_canvas -->|"inspect"| node_image_compare
node_refine_screen -->|"render"| node_skia_renderer
node_refine_screen -->|"inspect"| node_image_compare
node_bg_generator -->|"request"| node_api_service
node_bg_generator -->|"compose"| node_skia_renderer
node_style_jobs -->|"track"| node_style_job_store
node_edit_canvas -->|"start"| node_style_jobs
node_refine_screen -->|"continue"| node_style_jobs
node_export_screen -->|"finish"| node_style_jobs
node_contact_ctx -->|"support"| node_app_screens
node_battery_guard -->|"monitor"| node_battery_store
node_model_manager -->|"share"| node_model_store

click node_app_layout "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/_layout.tsx"
click node_app_tabs "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/tree/main/app/(tabs)"
click node_app_screens "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/tree/main/app/(screens)"
click node_camera_tab "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(tabs)/camera.tsx"
click node_gallery_tab "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(tabs)/gallery.tsx"
click node_edit_canvas "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/edit-canvas.tsx"
click node_refine_screen "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/refine.tsx"
click node_bg_generator "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/background-generator.tsx"
click node_export_screen "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/export.tsx"
click node_frame_processor "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/camera/useFrameProcessor.ts"
click node_inference_engine "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/inference/InferenceEngine.ts"
click node_tiled_runner "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/inference/TiledInferenceRunner.ts"
click node_model_manager "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/storage/ModelManager.ts"
click node_hardware_profiler "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/hardware/HardwareProfiler.ts"
click node_skia_renderer "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/canvas/SkiaRenderer.ts"
click node_style_jobs "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/style-transfer/StyleJobService.ts"
click node_image_selection "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/upload/hooks/useImageSelection.ts"
click node_battery_guard "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/battery/useBatteryGuard.ts"
click node_incoming_image "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/services/useIncomingImage.ts"
click node_api_service "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/services/api.ts"
click node_contact_ctx "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/context/ContactContext.tsx"
click node_battery_store "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useBatteryStore.ts"
click node_hardware_store "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useHardwareProfileStore.ts"
click node_model_store "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useModelStore.ts"
click node_style_job_store "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useStyleJobStore.ts"
click node_image_compare "https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/ui/ImageCompareSlider.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_app_tabs,node_app_screens,node_camera_tab,node_gallery_tab,node_edit_canvas,node_refine_screen,node_bg_generator,node_export_screen toneBlue
class node_frame_processor,node_inference_engine,node_tiled_runner,node_model_manager,node_hardware_profiler toneAmber
class node_skia_renderer,node_style_jobs,node_image_selection,node_battery_guard toneMint
class node_battery_store,node_hardware_store,node_model_store,node_style_job_store,node_image_compare toneRose
class node_incoming_image,node_api_service,node_contact_ctx toneIndigo
```

## Components

### App routes

Expo Router navigation, tabs, and task screens.

- [Router shell](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/_layout.tsx): expo-router layout · Top-level navigation structure and route composition. · `app/_layout.tsx`
- [Tab routes](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/tree/main/app/(tabs)): navigation tabs · Tabbed entry points for camera, gallery, home, styles, and settings. · `app/(tabs)`
- [Task screens](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/tree/main/app/(screens)): route screens · Editing, refinement, background generation, export, sharing, and support flows. · `app/(screens)`
- [Camera](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(tabs)/camera.tsx): camera route · Live capture entry point. · `app/(tabs)/camera.tsx`
- [Gallery](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(tabs)/gallery.tsx): gallery route · Library and intake entry point. · `app/(tabs)/gallery.tsx`
- [Edit canvas](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/edit-canvas.tsx): edit flow · Primary editing surface for composed output. · `app/(screens)/edit-canvas.tsx`
- [Refine](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/refine.tsx): refinement flow · Post-processing and adjustment screen. · `app/(screens)/refine.tsx`
- [Background gen](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/background-generator.tsx): generation flow · Background generation screen backed by external service. · `app/(screens)/background-generator.tsx`
- [Export](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/app/(screens)/export.tsx): output flow · Final save and sharing handoff. · `app/(screens)/export.tsx`

### Core engine

Camera capture, inference, hardware profiling, and model storage.

- [Frame processor](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/camera/useFrameProcessor.ts): vision camera · Per-frame hook that prepares live camera frames for inference. · `core/camera/useFrameProcessor.ts`
- [Inference engine](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/inference/InferenceEngine.ts): ml runtime · Executes on-device model inference for live and edited imagery. · `core/inference/InferenceEngine.ts`
- [Tiled runner](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/inference/TiledInferenceRunner.ts): tiling inference · Splits large images or frames into tiles to fit device memory limits. · `core/inference/TiledInferenceRunner.ts`
- [Model manager](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/storage/ModelManager.ts): model storage · Tracks model availability, loading, and readiness. · `core/storage/ModelManager.ts`
- [Hardware profile](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/core/hardware/HardwareProfiler.ts): device profiling · Captures device capability data used to tune runtime behavior. · `core/hardware/HardwareProfiler.ts`

### Feature services

Rendering, style jobs, upload, and battery gating.

- [Skia renderer](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/canvas/SkiaRenderer.ts): rendering · Composes the final visual result from inference output and source imagery. · `features/canvas/SkiaRenderer.ts`
- [Style jobs](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/style-transfer/StyleJobService.ts): async jobs · Coordinates style-transfer job creation, tracking, and persistence. · `features/style-transfer/StyleJobService.ts`
- [Image select](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/upload/hooks/useImageSelection.ts): upload intake · Normalizes gallery and selection inputs before editing. · `features/upload/hooks/useImageSelection.ts`
- [Battery guard](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/features/battery/useBatteryGuard.ts): power control · Limits or adapts expensive work based on battery state. · `features/battery/useBatteryGuard.ts`

### Shared layer

Global stores, UI primitives, and utilities.

- [Battery store](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useBatteryStore.ts): global state · Shared battery state for coordinated power-aware behavior. · `shared/stores/useBatteryStore.ts`
- [Hardware store](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useHardwareProfileStore.ts): global state · Shared device capability state used across the app. · `shared/stores/useHardwareProfileStore.ts`
- [Model store](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useModelStore.ts): global state · Shared model readiness and selection state. · `shared/stores/useModelStore.ts`
- [Job store](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/stores/useStyleJobStore.ts): global state · Shared style-job lifecycle state across screens. · `shared/stores/useStyleJobStore.ts`
- [Compare slider](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/shared/ui/ImageCompareSlider.tsx): ui component · Before/after inspection widget for edits and refinement. · `shared/ui/ImageCompareSlider.tsx`

### External integration

API access, incoming image normalization, contact support, and build/release automation.

- [Incoming image](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/services/useIncomingImage.ts): input normalization · Unifies images arriving from gallery picks, shares, and other entry points. · `services/useIncomingImage.ts`
- [API service](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/services/api.ts): remote api · External background generation and other server calls. · `services/api.ts`
- [Contact context](https://github.com/artlens-turn-every-frame-into-fine-art/artlens-frontend/blob/main/context/ContactContext.tsx): support context · Auxiliary support/contact data shared with the about/contact screen. · `context/ContactContext.tsx`

## Connections

- Router shell → Tab routes: routes · Defines the tabbed navigation surface.
- Router shell → Task screens: routes · Mounts the dedicated workflow screens.
- Tab routes → Camera: entry · Camera tab entry point.
- Tab routes → Gallery: entry · Gallery tab entry point.
- Task screens → Edit canvas: flow · Routes into the main editing surface.
- Task screens → Refine: flow · Routes into refinement.
- Task screens → Background gen: flow · Routes into background generation.
- Task screens → Export: flow · Routes into export and sharing.
- Camera → Frame processor: frames · Live camera frames are processed through the frame hook.
- Frame processor → Inference engine: infer · Per-frame data enters the inference runtime.
- Inference engine → Tiled runner: tile · Large inputs are split for constrained-device execution.
- Inference engine → Model manager: load · Inference depends on model availability.
- Inference engine → Hardware profile: adapt · Runtime behavior adapts to device capability.
- Hardware profile → Hardware store: persist · Profile data is shared through global state.
- Battery guard → Battery store: read · Consults shared battery state before expensive work.
- Battery guard → Inference engine: throttle · Can constrain inference intensity under low power.
- Gallery → Incoming image: ingest · Gallery and share inputs are normalized on entry.
- Incoming image → Image select: select · Selection hooks prepare the normalized image for editing.
- Incoming image → Edit canvas: open · Hands off normalized images to the editing flow.
- Edit canvas → Skia renderer: render · Edit surface composes the visible output.
- Edit canvas → Compare slider: inspect · Supports before/after comparison.
- Refine → Skia renderer: render · Refinement updates the rendered result.
- Refine → Compare slider: inspect · Uses comparison UI for evaluation.
- Background gen → API service: request · Calls the external generation backend.
- Background gen → Skia renderer: compose · Generated background is combined with local foreground rendering.
- Style jobs → Job store: track · Job lifecycle is shared across screens.
- Edit canvas → Style jobs: start · Editing can launch style-transfer jobs.
- Refine → Style jobs: continue · Refinement observes and updates style jobs.
- Export → Style jobs: finish · Export finalizes completed work.
- Contact context → Task screens: support · Supports the about/contact screen within task flows.
- Battery guard → Battery store: monitor · Battery state is shared for coordinated gating.
- Model manager → Model store: share · Model readiness is exposed through global state.