Skip to content

CLAUDE.md

Latest commit

 

History

History
148 lines (102 loc) · 5.54 KB

CLAUDE.md

File metadata and controls

148 lines (102 loc) · 5.54 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

# Build all modules
./gradlew.bat build

# Build specific module
./gradlew.bat :motmbrowser:assembleDebug
./gradlew.bat :mollib:build
./gradlew.bat :pdbparser:build

# Clean build
./gradlew.bat clean build

# Build release (requires gradle/signing.properties with STORE_FILE, STORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD)
./gradlew.bat :motmbrowser:assembleRelease

# Build release AAB (for Google Play)
./gradlew.bat :motmbrowser:bundleRelease

Release Build with R8 Obfuscation

Release builds use R8 for code shrinking and obfuscation. R8 scrambles function names (e.g., calculateUserScore() becomes a()) to reduce file size and protect intellectual property.

Mapping files are automatically included in the AAB under BUNDLE-METADATA/ (AGP 9.0.1). Google Play uses these to deobfuscate crash reports automatically - no manual upload required.

For local debugging, mapping files are generated at:

  • motmbrowser/build/outputs/mapping/release/mapping.txt

ProGuard rules are in motmbrowser/src/main/proguard-motmbrowser.pro.

Version Management

Version numbers are in motmbrowser/build.gradle.kts:

val versionMajor = 2
val versionMinor = 9
val versionPatch = 3
val versionBuild = 2903

Update these before creating a new release.

Testing

# Run all tests
./gradlew.bat test

# Run mollib unit tests only
./gradlew.bat :mollib:test

# Run motmbrowser unit tests only
./gradlew.bat :motmbrowser:testDebugUnitTest

# Run a single test class
./gradlew.bat :mollib:test --tests "com.bammellab.mollib.data.CorpusTest"

# Run a single test method
./gradlew.bat :mollib:test --tests "com.bammellab.mollib.data.CorpusTest.testCorpusSize"

# Run pdbparser unit tests only
./gradlew.bat :pdbparser:test

# Run a single pdbparser test class
./gradlew.bat :pdbparser:test --tests "com.kotmol.pdbParser.AtomCoordTest01"

# Run release build verification tests (requires bundleRelease first)
./gradlew.bat :motmbrowser:testDebugUnitTest --tests "com.bammellab.motm.release.ReleaseBuildTest"

Tests use JUnit 5 (Jupiter) with Truth assertions. Test files are in mollib/src/test/java/ and motmbrowser/src/test/java/.

Some tests in CorpusTest and MotmByCategoryTest make live network calls to pdb101.rcsb.org to verify local data is in sync with the website — they skip gracefully if the network is unavailable.

See TESTING.md for complete testing documentation.

Linting

./gradlew.bat lint

Lint configuration is in lint.xml at the repository root.

Architecture

This is a multi-module Android project written in Kotlin that displays 3D molecular structures from the RCSB Protein Data Bank "Molecule of the Month" series.

Modules

  • motmbrowser/ - Main Android application

    • MVVM architecture with ViewModels and Fragments
    • AndroidX Navigation for fragment navigation (bottom nav: Browse / Search / Settings)
    • Molecule detail opens MotmDetailActivity; 3D viewer opens MotmGraphicsActivity
    • Key packages: browse/, search/, detail/, graphics/, settings/

  • mollib/ - Core library (shared across all apps)

    • objects/ - OpenGL ES rendering (RendererDisplayPdbFile, BufferManager, RenderRibbon, etc.)
    • data/ - Static molecule data bundled with the app (PDBs.kt, Corpus.kt, MotmByCategory.kt)
    • common/math/ - 3D math utilities (Matrix4, Quaternion, MotmVector3)
    • pdbDownload/ - Network download with OkHttp3

  • pdbparser/ - Local copy of the KotmolPdbParser library (pure Kotlin/JVM module)

    • Package: com.kotmol.pdbParser
    • Core classes: ParserPdbFile (Builder pattern), Molecule (output container), PdbAtom, BondInfo, AtomInformationTable, ChainRenderingDescriptor
    • 23 unit tests covering atom coords, bond tables, secondary structure, insertion codes
    • Upstream source: C:\a\j\kotlinIdea\KotmolPdbParser; see README-pdbparser.md

  • standalone/ - Test app for graphics development (loads PDB files from /storage/emulated/0/PDB/)

  • captureimages/ - Utility for generating PDB thumbnail images (output uploaded to jimandreas/MotmImages on GitHub)

  • screensaver/ - Muzei live wallpaper plugin

Key Technical Details

  • OpenGL ES 2.0/3.0 for 3D molecule rendering
  • PDB file parsing via the local :pdbparser module (com.kotmol.pdbParser)
  • Target SDK 36, min SDK 23, Java 17
  • Networking: OkHttp3 + Retrofit2
  • Image loading: Glide (with KSP annotation processing) and Picasso
  • Dependencies managed via Gradle version catalog (gradle/libs.versions.toml)

Data Flow

  • Static data (bundled): Corpus.kt (MotM titles/dates), PDBs.kt (MOTM→PDB mappings), MotmByCategory.kt (categories)
  • MotM article images: fetched from github.com/jimandreas/MotmImages (self-hosted thumbnails)
  • PDB structure files: downloaded on demand from files.rcsb.org/download/ via PdbFetcherCoroutine
  • MotM article pages: opened as WebView pointing to pdb101.rcsb.org/motm/

Rendering Pipeline

The OpenGL rendering uses an MVP (Model-View-Projection) matrix architecture:

  • RendererDisplayPdbFile - Main GLSurfaceView.Renderer handling frame drawing
  • BufferManager - Manages vertex buffer objects for molecule geometry
  • Shaders: Per-vertex (Lesson 2) and per-pixel (Lesson 3) lighting modes
  • Touch input controls rotation (deltaX/Y) and pinch-to-zoom (scaleCurrentF)

Test PDB Files

  • Small: 1AEW (cadmium with bonds)
  • Large: 1BGL (two complexes)
  • Edge cases: 1IDR, 1B89 (orphan atoms)