# dector/lampa architecture

> Architecture diagram of the GitHub repository dector/lampa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dector/lampa
- Repository: https://github.com/dector/lampa

## Overview

##### Project type and purpose
- Lampa is a Go-based command-line tool (open-source utility) for Android developers.
- Its primary purpose is to scan an Android/Gradle project’s third-party dependencies, produce JSON and HTML reports for a single build, and generate comparative HTML diffs between two releases.

##### File structure
- Top-level directories:
- cmd/cli – entrypoints and subcommands (collect, compare, doctor)
- internal – reusable application logic (Android locator, Git integration, parsers, report generation, templates, spinner/UI helper, utilities)
- pkg – protocol definitions and bundle-parsing logic (Gradle bundles, Protobuf schemas)
- docs, samples – usage docs and example reports
- Configuration/build files: go.mod, Taskfile.yml, .tool-versions
- CI/CD: GitHub workflows for build, test, release, renovate, snapshot, triage

##### Key insights from the README
- Three main CLI commands:
- collect: scan local project, emit JSON or HTML report
- compare: take two JSON snapshots, emit diff HTML
- doctor: diagnose environment issues
- Runtime external dependencies: Java (for invoking Gradle)
- Template-driven HTML generator (using Tailwind & Alpine in internal/assets)

##### Main components and their interactions
a. Components
1) CLI Layer (cmd/cli)
- Argument parsing (cobra or custom)
- Dispatch to subcommands: collect, compare, doctor
2) Project Locator & Loader (internal/android, internal/git)
- Locate Android project root, verify Git repo, fetch VCS metadata if needed
3) Build Metadata Extractor (pkg/gradle, pkg/bundles)
- Invoke Gradle (via Java) to produce dependency bundle metadata
- Parse AOSP Protobuf schemas to unify bundle model
4) Core Parsers (internal/parsers.go)
- Transform raw bundle data into the tool’s internal models
5) Report Generator (internal/report)
- Produce JSON report (models → JSON writer)
- Produce diff report (two JSON models → diffreport)
6) Template Engine (internal/templates + internal/assets)
- HTML templates for single and comparative views
- JS/CSS assets (Tailwind, Alpine) embedded via internal/assets.go
7) Output & Logging (internal/out, internal/spinner)
- Spinner/progress UI on stdout
- Log messages, write output files to disk

b. Relationships & Data Flow
- User invokes `lampa <command>` → CLI Layer parses args →
- For collect: call Project Locator → Build Metadata Extractor → Core Parsers → Report Generator → Template Engine (if HTML) → write files via Output module.
- For compare: load two JSON models from disk → Report Generator.diffreport → Template Engine → write diff HTML.
- doctor: run environment checks via Android Locator, Git, Java/Gradle detection → report to user.

c. Architectural patterns & principles
- Modular package structure (clear separation of cmd vs. internal vs. pkg)
- Single-responsibility packages: parsing, templating, reporting
- Template-driven UI layer for HTML, decoupled from core logic
- Embedding static assets in Go for single-binary distribution

d. Key technologies/frameworks
- Go standard library + cobra-style CLI
- Gradle invocation (via exec Java)
- Protobuf (AOSP schemas) for bundle definitions
- Go’s text/template or html/template for HTML generation
- Tailwind CSS & Alpine.js for HTML assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Invocation
    User["User"]:::external -->|"lampa <command>"| CLI

    subgraph "CLI Layer"
        CLI["CLI Layer"]:::go
    end

    subgraph "Project Locator & Loader"
        Locator["Project Locator & Loader"]:::go
    end

    subgraph "Build Metadata Extractor"
        Extractor["Build Metadata Extractor"]:::go
    end

    subgraph "Core Parsers"
        Parsers["Core Parsers"]:::go
    end

    subgraph "Report Generator"
        Reporter["Report Generator"]:::go
    end

    subgraph "Template Engine & Assets"
        Templates["Template Engine & Assets"]:::template
    end

    subgraph "Output & Logging"
        Output["Output & Logging"]:::go
    end

    %% External Systems
    JavaGradle["Java/Gradle"]:::external
    Git["Git"]:::external
    FS["Filesystem"]:::external

    %% Data Flows
    CLI -->|"invoke locator"| Locator
    Locator -->|"project root & VCS metadata"| Extractor
    Extractor -->|"Raw Gradle metadata"| Parsers
    Parsers -->|"Internal models"| Reporter
    Reporter -->|"JSON report"| Output
    Reporter -->|"HTML report"| Templates
    Templates -->|"render HTML"| Output
    Output -->|"write files"| FS

    %% Compare command flow
    subgraph "Compare Flow" 
        CLI -->|"load two JSON snapshots"| Reporter
    end
    Reporter -->|"diffreport models"| Templates

    %% Doctor command flow
    subgraph "Doctor Flow"
        CLI -->|"env checks"| Locator
        Locator -->|"check Git"| Git
        Locator -->|"check Java/Gradle"| JavaGradle
        JavaGradle -->|"status"| Output
        Git -->|"status"| Output
    end

    %% Click Events
    click CLI "https://github.com/dector/lampa/tree/trunk/cmd/cli"
    click Locator "https://github.com/dector/lampa/blob/trunk/internal/android/locator.go"
    click Git "https://github.com/dector/lampa/blob/trunk/internal/git/git.go"
    click Extractor "https://github.com/dector/lampa/blob/trunk/pkg/gradle/gradle.go"
    click Parsers "https://github.com/dector/lampa/blob/trunk/internal/parsers.go"
    click Reporter "https://github.com/dector/lampa/blob/trunk/internal/report/parser.go"
    click Templates "https://github.com/dector/lampa/blob/trunk/internal/templates/model.go"
    click Output "https://github.com/dector/lampa/blob/trunk/internal/out/log.go"

    %% Styles
    classDef go fill:#e0f2ff,stroke:#0277bd,color:#000;
    classDef external fill:#e8f5e9,stroke:#2e7d32,color:#000;
    classDef template fill:#fff3e0,stroke:#ef6c00,color:#000;
```
