# 1weiho/next-lens architecture

> Architecture diagram of the GitHub repository 1weiho/next-lens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1weiho/next-lens
- Repository: https://github.com/1weiho/next-lens

## Overview

##### Project Type and Purpose
- This is a Node.js/TypeScript-based CLI tool (“next-lens”) that scans Next.js App Router projects to report page and API routes plus framework/package info.
- It follows a modular “command” architecture (see `src/commands/*.ts`) and uses TSup for bundling, Vitest for testing, and GitHub Actions for CI.

##### File Structure
- Top‐level files:
– `src/index.ts`: CLI entry point and command dispatcher.
– `src/commands/`: Individual command modules (`about.ts`, `api-list.ts`, `page-list.ts`, `info.ts`).
- Config/build/test:
– `tsup.config.ts` (bundler), `vitest.config.ts` (test runner), GitHub workflows for CI (`.github/workflows/ci.yml`).
- Tests and fixtures: isolated unit tests and mock Next apps under `tests/`.

##### Extract Key Architectural Insights from README
- Core workflow: user runs `next-lens <command> [target]` → CLI dispatcher loads the proper command →
– Commands perform a recursive directory walk (skipping build folders).
– For page routes: scan `app/**/page.*`, check co-located/inherited `loading` & `error` files.
– For API routes: parse `route.*` files’ AST to detect exported handler methods.
– For info: read `package.json` + lockfile to detect versions and package manager.

##### Main Components & Relationships
a. CLI Entry & Dispatcher
- Component: `CLI Runner` (src/index.ts)
- Role: parse arguments, instantiate the corresponding `Command` class, invoke its `execute()` method.
b. Command Modules
- Components: `AboutCommand`, `ApiListCommand`, `PageListCommand`, `InfoCommand`
- Role: define high-level workflows and coordinate scanning, parsing, and rendering.
c. File System Walker
- Component: `RouteDiscovery`
- Role: traverse the project directory, filter files by naming conventions (page, route).
d. AST Parser & Route Mapper
- Component: `HandlerParser` (using TypeScript Compiler API)
- Role: parse `.ts/.tsx` route files to extract HTTP methods.
e. Page Boundary Analyzer
- Component: `BoundaryScanner`
- Role: detect `loading` / `error` co-located or inherited files.
f. Package/Framework Inspector
- Component: `InfoFetcher`
- Role: read `package.json`, lockfiles, and installed modules to report versions & PM.
g. Renderer
- Component: `ConsoleRenderer`
h. External Services & Dependencies
- File system (fs) module
- TypeScript Compiler API
- PNPM/NPM for package metadata

##### Architectural Patterns & Principles
- Command Pattern: each CLI action is encapsulated in its own module with a common interface (`execute()`).
- Single Responsibility: scanning, parsing, and rendering are separated to simplify testing and extension.
- Test fixtures isolate real-world examples (mock Next apps) for deterministic testing of discovery logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "next-lens CLI"
        CR["CLI Runner"]:::core
        CD["Command Dispatcher"]:::core
        CR -->|"parse args"| CD
        subgraph "Commands"
            AC["AboutCommand"]:::core
            APIC["ApiListCommand"]:::core
            PLC["PageListCommand"]:::core
            IC["InfoCommand"]:::core
        end
        CD --> AC
        CD --> APIC
        CD --> PLC
        CD --> IC

        subgraph "ApiList Flow"
            APIC --> RD1["RouteDiscovery"]:::core
            RD1 --> HP["HandlerParser"]:::core
            HP --> DM1["Data Model"]:::core
            DM1 --> CRR["ConsoleRenderer"]:::core
        end

        subgraph "PageList Flow"
            PLC --> RD2["RouteDiscovery"]:::core
            RD2 --> BS["BoundaryScanner"]:::core
            BS --> DM2["Data Model"]:::core
            DM2 --> CRR
        end

        subgraph "Info Flow"
            IC --> IF["InfoFetcher"]:::core
            IF --> DM3["Data Model"]:::core
            DM3 --> CRR
        end
    end

    subgraph "External Dependencies"
        FS["fs (Node)"]:::external
        TSAPI["TypeScript Compiler API"]:::external
        Chalk["Chalk/colors lib"]:::external
    end

    RD1 -->|"walk file tree"| FS
    RD2 -->|"walk file tree"| FS
    HP -->|"parse AST"| TSAPI
    BS --> FS
    IF --> FS

    subgraph "Build & Test Pipeline"
        TSUP["TSup Bundler"]:::pipeline
        VIT["Vitest Runner"]:::pipeline
        CI["GitHub Actions CI"]:::pipeline
        UT["Unit Tests"]:::pipeline
        TF1["Mock Next.js App Fixture"]:::pipeline
        TF2["Mock Info App Fixture"]:::pipeline
        TF3["Mock Info Package Manager Fixture"]:::pipeline
        TSUP -->|"bundle src"| CR
        VIT -->|"run tests"| UT
        VIT --> TF1
        VIT --> TF2
        VIT --> TF3
        CI --> VIT
    end

    click CR "https://github.com/1weiho/next-lens/blob/main/src/index.ts"
    click AC "https://github.com/1weiho/next-lens/blob/main/src/commands/about.ts"
    click APIC "https://github.com/1weiho/next-lens/blob/main/src/commands/api-list.ts"
    click PLC "https://github.com/1weiho/next-lens/blob/main/src/commands/page-list.ts"
    click IC "https://github.com/1weiho/next-lens/blob/main/src/commands/info.ts"
    click TSUP "https://github.com/1weiho/next-lens/blob/main/tsup.config.ts"
    click VIT "https://github.com/1weiho/next-lens/blob/main/vitest.config.ts"
    click CI "https://github.com/1weiho/next-lens/blob/main/.github/workflows/ci.yml"
    click UT "https://github.com/1weiho/next-lens/tree/main/tests/commands"
    click TF1 "https://github.com/1weiho/next-lens/tree/main/tests/fixtures/mock-next-app"
    click TF2 "https://github.com/1weiho/next-lens/tree/main/tests/fixtures/mock-info-app"
    click TF3 "https://github.com/1weiho/next-lens/tree/main/tests/fixtures/mock-info-package-manager"

    classDef core fill:#D0E8FF,stroke:#0366d6
    classDef external fill:#DFFFE0,stroke:#22863a,shape:ellipse
    classDef pipeline fill:#EFEFEF,stroke:#666
    class CR,CD,AC,APIC,PLC,IC,RD1,RD2,HP,BS,IF,DM1,DM2,DM3,CRR core
```
