# Repository Layout

Guide to files and folders at the Scanly repository root.

## Top-level structure

```
Scanly/
├── app/                    # Android application module
├── gradle/                 # Wrapper + libs.versions.toml
├── docs/                   # Complete project documentation (start at docs/README.md)
├── scanly-web/             # Separate React website repository checkout
├── screenshots/            # UI screenshots for README
├── scripts/                # Dev utilities (performance-seed load testing)
├── keystore/               # Release keystore (gitignored in practice)
├── README.md               # Public landing page
├── CHANGELOG.md            # Release notes
├── VERSION.md              # Version metadata
├── CONTRIBUTING.md         # Contribution guide
├── SECURITY.md             # Vulnerability reporting
├── Agents.md               # AI agent guidance
├── OPEN_SOURCE_NEXT_STEPS.md  # Maintenance checklist
├── LICENSE                 # AGPL-3.0-only
├── build.gradle.kts        # Root build file
├── settings.gradle.kts     # Module settings
└── gradle.properties       # Gradle config
```

## `app/` module

```
app/
├── build.gradle.kts        # SDK, version, deps, signing, build types
├── proguard-rules.pro      # R8 rules for release
└── src/
    ├── main/
    │   ├── AndroidManifest.xml
    │   ├── java/in/c1ph3rj/scanly/   # All Kotlin source
    │   ├── assets/                    # ML model, FAQs, licenses
    │   └── res/                       # Compose theme, icons, FileProvider paths
    ├── debug/                         # Local debug update binding
    ├── githubRelease/                 # GitHub release update binding
    ├── playStoreRelease/              # Google Play release update binding
    ├── test/                          # Unit tests (40 files)
    └── androidTest/                   # Instrumented tests (3 files)
```

## Key source files

| File | Purpose |
| --- | --- |
| `MainActivity.kt` | App shell |
| `ScanlyApplication.kt` | Hilt application |
| `navigation/ScanlyNavHost.kt` | Navigation |
| `data/local/db/ScanlyDatabase.kt` | Room schema (v5) + migrations |
| `data/page/DefaultPageRepository.kt` | Capture finalize and page edits |
| `feature/editor/` | Page editor, Filters/Adjust overlays, crop route |
| `data/export/DefaultDocumentExportRepository.kt` | Export |
| `data/storage/DocumentStorageManager.kt` | File I/O |
| `data/archive/LibraryArchiveEngine.kt` | `.scanly` backup, validation, and restore |
| `data/archive/LibraryArchiveWorker.kt` | Foreground WorkManager backup/restore |
| `data/export/DefaultExportStorageRepository.kt` | Save exports to configured destination |
| `core/ml/` | Corner detector, document gate, book/quad policies, automatic model selector |
| `core/processing/` | Filters, adjustments, perspective warp |

## `docs/` documentation map

| Folder | Contents |
| --- | --- |
| `docs/overview/` | Product context, features, user guide |
| `docs/architecture/` | Layers, navigation, screens |
| `docs/data/` | Room, files, settings, updates |
| `docs/processing/` | Capture, ML, filters, export |
| `docs/development/` | Setup, conventions, testing, releasing |
| `docs/reference/` | Models, use cases, tech stack, snapshot |

**Start here:** [docs/README.md](../README.md)

## `scanly-web/` website

`scanly-web/` is a separately versioned checkout of `github.com/c1ph3rj/scanly-web`, not an Android Gradle module. Its deployed React application:

- fetches validated landing-page content from `scanly-web/content/site-content.json` on GitHub
- reads the latest stable release from the Scanly GitHub Releases API
- discovers and renders this repository's `docs/**/*.md` files under `/docs`
- keeps a bundled content snapshot and browser cache as fallbacks

The website defaults to both repositories' `master` branches. Preview builds can override the Scanly docs ref with `VITE_SCANLY_GITHUB_REF` and the website content ref with `VITE_SCANLY_WEB_CONTENT_REF`.

## Related docs

- [../overview/what-is-scanly.md](../overview/what-is-scanly.md) — what the project is
- [../architecture/overview.md](../architecture/overview.md) — code package layout