Project structure

This page is for a developer who has just cloned the repository and wants to know what everything is, how the pieces talk to each other, and where to go to change something. It stays high level: after reading it you should be able to open the right file for any change.

Opensolr Photos is a single Android app written in Kotlin, with its screens built in Jetpack Compose. There is no server of its own: everything it needs on the server side is an Opensolr service it calls over HTTPS (see every call it makes). Inside the app there are three flows, and almost every file belongs to one of them:

Everything below lives under app/src/main/java/com/opensolr/photos/. The packages are listed from the bottom of the stack (things that know nothing about screens) to the top (the screens).

data/ — what the app remembers

• Models.kt — the plain data classes the rest of the app passes around: the signed-in Session, the IndexConnection (address and password of the index), AccountLimits (with the photos-per-month arithmetic), SyncSchedule and SyncReport.
• AppPrefs.kt — every setting and saved value, in one private preferences file. If you need to remember something new between runs, add a property here.
• SecureStore.kt — encrypts and decrypts the two secrets with a Keystore key. AppPrefs calls it; nothing else should store a secret any other way.
• PhotoCache.kt — the SQLite table of documents and vectors already paid for, so a photo is never read twice.

net/ — talking to Opensolr

• Http.kt — the one shared HTTP client, with its timeouts and no redirects.
• OpensolrApi.kt — one function per Opensolr call: token exchange, index list, create, config upload, connection details, account summary, image_clip, batch_embed, embed. It also turns the platform's refusals into typed errors.
• SolrClient.kt — talks straight to the phone's index: search, list every id, add, delete, commit, check the schema.
• Errors.kt — the exceptions, named after what the app has to do about them (sign in again, quota used up, plan limit, rate limited, photo rejected...).

media/ — photos on the phone

• MediaScanner.kt — lists folders, scans the chosen ones, and holds photoId(), the one place a photo's id is computed.
• PhotoReader.kt — reads EXIF metadata and makes the upright 640 px copy sent to be read.

index/ — the phone's index

• IndexManager.kt — the index name, finding it, creating it, choosing its environment, uploading the configuration, and re-reading its password. The rule “only create when certainly missing” lives here.

auth/ — signing in

• AuthFlow.kt — builds the PKCE request and opens the browser.
• AuthCallbackActivity.kt — a tiny invisible screen Android opens at the end of the sign-in; it only forwards the address to the main screen.

sync/ — keeping the index in step

• SyncEngine.kt — the sync algorithm itself, from “is the index there” to the final commit, including every stop condition. This is the heart of the app.
• SyncWorker.kt — runs the engine as a background job with a progress notification, and makes sure only one runs at a time.
• SyncScheduler.kt — starts a sync now, sets the weekly or monthly schedule, and exposes the live status the screens show.
• Notifier.kt — every notification the app posts.

search/ — finding photos

• SearchRepository.kt — builds the Solr request from the text and the filters (words, meaning, facets) and parses the answer into results.

ui/ — the screens

• AppViewModel.kt — the brain of the interface: one UiState value holding everything the screens draw, and one function per thing the user can do (sign in, save folders, search, force a re-sync, sign out...).
• AppRoot.kt — picks which screen to draw from UiState.screen.
• screens/ — the screens: sign-in, welcome, permissions, folders and setup in OnboardingScreens.kt; SearchScreen.kt with the filter and details sheets; SyncScreen.kt; AccountScreen.kt.
• Components.kt — the shared building blocks: buttons, notices, labelled rows, usage bars, headers.
• Actions.kt — things handed to other apps (open a photo, a map, a web page) and the date and number formats.
• theme/Theme.kt — colours, typography and shapes, light and dark.

At the top

• MainActivity.kt — the one real screen of the app: it hosts the Compose UI and passes sign-in callbacks and notification taps to the view model.
• PhotosApp.kt — runs once when the app starts and creates the notification channels.

Sign-in

1. SignInScreen button → AppViewModel.beginSignIn() → AuthFlow.start() saves the verifier and state in AppPrefs and opens the browser.
2. Android opens AuthCallbackActivity, which forwards the address to MainActivity.
3. AppViewModel.completeSignIn() checks the state and calls OpensolrApi.exchangeCode().
4. The session and plan limits go into AppPrefs; the welcome screen shows the limits.

Sync

1. SyncScheduler.runNow() (or the schedule) starts SyncWorker, which runs SyncEngine.run().
2. IndexManager.ensure() makes sure the index exists, using OpensolrApi.
3. MediaScanner.scan() lists the photos; SolrClient.allIds() lists the index.
4. For new photos: PhotoCache or PhotoReader + OpensolrApi.imageClip(), then batchEmbed(), then SolrClient.add().
5. The SyncReport is saved; SyncScheduler.status() lets the screens redraw.

Search

1. Typing and pressing search → AppViewModel.search().
2. SearchRepository.search() may call OpensolrApi.embedQuery(), then SolrClient.select().
3. The results and facets go into UiState; SearchScreen draws them; a tap calls Actions.openPhoto().

• Read building from source to get a debug build running on your phone.
• Read contributing for the conventions and the security rules every change keeps.
• Ask for contributor access at support@opensolr.com.