Skip to content

PDR.md

Latest commit

 

History

History
115 lines (84 loc) · 5.47 KB

PDR.md

File metadata and controls

115 lines (84 loc) · 5.47 KB
Raw

Project Design Document (PDR) — AppDimens Dynamic

Note

Product Alignment: io.github.bodenberg:appdimens-dynamic:3.1.5 Associated Documents: PRD (Requirements) | Mathematics | Performance Specs

This internal architecture document mandates the precise structural logic, technical dependencies, caching behaviors, and quality integration required by the AppDimens Dynamic library package.

1. Traceability & Package Matrix

Core Index: 180 .kt logical components under library/src/main/java/com/appdimens/dynamic/.

Subsystem Domain Crucial Topologies Domain Core Strategy Active Verification Gates
core / common DimenCache, ResizeMath, DpQualifier Unified Mathematics & Core cache. DimenCacheTest, DimenPerformanceTest
compose.scaled DimenScaled, *Extensions Base Reference Anchors StrategyModuleFormulasTest
compose.percent DimenPercentSpace, DimenPercentPlainPx Context Fractions StrategyModuleFormulasTest
compose.geometric diagonal, perimeter, fit, fill Shape/Geometric Scaling StrategyModuleFormulasTest
code.plain DimenPlainBranch.kt Raw Context Contextualing DimenPlainBranchTest
compose.resize DimenResize Asymptotic Search Subsystem DimenResizeCodeUnitTest

2. Technical System Architecture

2.1 Unified Interaction Flow

flowchart TD
  subgraph Input Context
    UI_Mode[UiModeType]
    Qualifiers[DpQualifier]
    Config[Device Configuration]
  end

  subgraph Processing & Cache Pipeline
    Plumbing(DimenCalculationPlumbing)
    CacheCore[[DimenCache Engine]]
    Constraints{ResizeBound / Fits?}
  end

  subgraph Output Targets
    TreeCompose((Compose Strategy))
    TreeCode((Code Strategy))
  end

  Config --> Plumbing
  Qualifiers --> Plumbing
  UI_Mode --> Plumbing

  Plumbing --> CacheCore
  Plumbing --> Constraints
  Constraints --> TreeCompose & TreeCode
  CacheCore --> TreeCompose & TreeCode

  style CacheCore fill:#2A4365,stroke:#fff,stroke-width:2px,color:#fff
Loading

Important

Architectural Invariant: Code/Modules defined as compose.<strategy> must never intersect or implicitly construct elements of a differing strategy module. Code routing is strict: strategy (\rightarrow) core (\rightarrow) common.

2.2 Cache Anatomy & Thread Engineering

The DimenCache Subsystem calculates, stores, and evaluates layout keys natively using bitwise parameters on primitive vectors to minimize Garbage Collection penalties.

  • 64-bit Payload Signature: Keys generated using a complex boolean flag logic including parameters: applyAspectRatio, baseValue(float_bits), CalcType_Enum, DpQualifier, and multiWindowConstraints.
  • State Bypass Architecture: Core types (PERCENT, SCALED, DENSITY) natively bypass associative shard writing when aspect ratios are inactive, generating results strictly based on raw mathematics for near-zero timing (refer to PERFORMANCE.md).
  • Volatility Pre-rendering: ScreenFactors are preemptively evaluated and hot-swapped during configuration changes, pushing heavy logarithmic calculations completely outside of the Compose recomposition phase.

3. Asymptotic Resize Constraint Mechanism

The resize layer runs distinct logic isolated from general curves, dedicated exclusively to rendering bounds to physical limits.

sequenceDiagram
    participant UI Component as App Widget
    participant ResizeMath as Resize Core
    participant TestLogic as Fits Predicate

    UI Component->>ResizeMath: Provide (minPx, maxPx, stepPx)
    Note over ResizeMath: Generates FloatArray buffer (No Auto-box)
    ResizeMath->>ResizeMath: buildResizeStepsPx()
    ResizeMath->>TestLogic: Binary Search \(\mathcal{O}(\log N)\)
    loop Constraints Test
        TestLogic-->>ResizeMath: check() against bounds predicate
    end
    ResizeMath-->>UI Component: findLargestFittingResizePx() Result
Loading

4. Development Quality & Reliability Matrix

4.1 Release Constraints

  1. Module Artifacting: Built and aligned under the standard Kotlin multiplatform mavenPublishing protocol targeting Maven Central.
  2. Obfuscation Integrity: Comprehensive ProGuard rules (consumer-rules.pro) ensure public API parity and runtime stability natively.

4.2 Known Technical Risk Mapping

Monitored Technical Risk Built-In Mitigation & Failsafes
ARM64 Cache Desynchronization Cache primitives strictly tagged with @Volatile. Active concurrency verified in DimenCacheRaceTest.
R8 Heavy Obfuscation Stripping Dedicated consumer rules preserving reflection vectors unstripped (Refer to R8-PROGUARD.md)
Dokka HTML API Drift Scripts provided locally scripts/sync_kdoc_from_dokka_html.py correct ERROR CLASS issues caused by Jetpack Compose compiler nuances.

5. System Check protocols for Engineering Mates

When modifying structural parameters or curves, engineers must ensure the following baseline protocols are met prior to merging PRs:

  • Ensure Code/Compose Parity. Modify the code extension symmetrically when introducing a new Compose builder.
  • Execute ./gradlew :library:test and visually cross-check output against DimenPerformanceTest.
  • If mutating ScreenFactors, actively adjust bits in DimenCache alongside mathematical models evaluated in MATHEMATICS-AND-CALCULUS.md.