# fast-light/fastaop architecture

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

- Interactive diagram: https://gitdiagram.com/fast-light/fastaop
- Repository: https://github.com/fast-light/fastaop

## Overview

##### Project Type and Purpose
- The project is divided into multiple Maven modules:
- A runtime module (the “fastaop” module) that holds the core AOP functionality, including annotations, handlers, processors, translators, and utilities.
- An annotation processing module (the “fastapt” module) containing the annotation processor, models, translation logic, and utility classes for compile-time AOP code generation.
- An example module that demonstrates how to use the framework in a Java application.

##### Analyzing the File Structure
- Top-level directories such as “fastaop”, “fastapt”, and “example” clearly demarcate the system’s components.
- Within “fastaop” you see subdirectories like “aop/annotation”, “aop/handler”, “aop/processor”, “aop/translator”, and “aop/util” – indicating a pattern where annotations are defined and then processed via various handler and translator components.
- The “fastapt” module mirrors much of this organization with directories for annotation’s processor, translator, model, and compile components. This suggests a well-separated design between the runtime AOP support and the compile-time annotation processing logic.
- The “example” folder contains an application with its own src structure, demonstrating AOP usage with example classes and handlers (e.g., LogAccess, LogHandler, AopExample).

a. Main Components to Represent:
- FastAOP Runtime (fastaop): Contains core components such as:
- Annotation Definitions (e.g., FastAspect, FastAspectAround, FastAspectVar, FastNone)
- AOP Handlers (e.g., FastAspectHandler, FastAspectContext)
- Processors and Translators (e.g., FastAspectProcessor, FastAspectAroundTranslator, FastAspectVarTranslator)
- Utility Classes (e.g., FastAspectProperties, BannerLogger)
- FastAPT Annotation Processing (fastapt): Responsible for compile-time processing and code generation:
- Annotation Processor Base Classes (BaseAnnotationProcessor, BaseFastProcessor, etc.)
- Models representing metadata (MetaAnnotation, MetaMethod, MetaType, etc.)
- Compile Models (AnnotationCompile, ClassCompile, etc.)
- Translators (BaseFastTranslator)
- Example Application Module:
- Demonstrates integration of the annotation-based AOP functionality.
- Contains classes that utilize the AOP annotations and handlers (example/AopExample, LogAccess, LogHandler)

b. Relationships and Interactions:
- At compile time, the fastapt module’s annotation processors scan the code in the example application (and any application using the framework) for AOP annotations defined in the fastaop module.
- During runtime, the fastAOP runtime component (fastaop) provides the implementation of the aspect logic via its handlers, context management, and utility services.
- The example module interacts with the runtime AOP layer, thus demonstrating how user code benefits from the modifications made at compile time.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Clear distinction between compile-time processing (fastapt) and runtime execution (fastaop).
- Annotation-driven Design: Uses annotations to directly modify behavior at compile time (using Java’s Annotation Processing API).
- Modularity: The design is broken down into multiple Maven modules, each focusing on a specific aspect of the framework.
- Extendability: The layered design (with processors, translators, handlers) allows for future extensions or enhancements of the AOP logic.

- Use of Java Annotation Processing and highlight that the framework is designed to work with Java 8.

##### Final Elements
- Each component should have clear labels (e.g., “FastAOP Runtime”, “FASTAPT Annotation Processor”, “Example Application”).
- The processing flow from the example source code to the annotation processor (fastapt) and then to the runtime enhancements in fastaop.
- Dependencies between modules (e.g., the example module depends on both fastapt and fastaop).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Example Module
    subgraph "Example Module"
        E["Example Application"]:::example
    end

    %% Compile-Time (FastAPT)
    subgraph "Compile-Time (FastAPT)"
        AP["Annotation Processors"]:::compile
        M["Models"]:::compile
        CM["Compile Models"]:::compile
        AT["Translator"]:::compile
        AU["APT Utilities"]:::compile
    end

    %% Runtime (FastAOP)
    subgraph "Runtime (FastAOP)"
        AN["Annotations"]:::runtime
        HA["Handlers"]:::runtime
        PR["Processors"]:::runtime
        TR["Translators"]:::runtime
        AU2["AOP Utilities"]:::runtime
    end

    %% Flow Connections - Compile Time Path
    E -->|"scansForAnnotations"| AP
    AP -->|"buildsMetadata"| M
    M -->|"convertsToModels"| CM
    CM -->|"translatesAOP"| AT

    %% Flow Connections - From Compile-Time to Runtime
    AT -->|"injectsLogic"| AN
    AT -->|"generatesTranslatorCode"| TR
    TR -->|"processesMethods"| PR
    PR -->|"invokesAspectLogic"| HA

    %% Direct Dependency: Example uses Runtime AOP
    E -->|"usesAOPRuntime"| HA

    %% Supporting utilities in Runtime
    AU2 -->|"supportsHandlers"| HA

    %% Styling for clarity
    classDef example fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef compile fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef runtime fill:#add8e6,stroke:#000,stroke-width:2px;

    %% Click Events for FastAOP Runtime
    click AN "https://github.com/fast-light/fastaop/tree/master/fastaop/src/main/java/org/fastlight/aop/annotation"
    click HA "https://github.com/fast-light/fastaop/tree/master/fastaop/src/main/java/org/fastlight/aop/handler"
    click PR "https://github.com/fast-light/fastaop/tree/master/fastaop/src/main/java/org/fastlight/aop/processor"
    click TR "https://github.com/fast-light/fastaop/tree/master/fastaop/src/main/java/org/fastlight/aop/translator"
    click AU2 "https://github.com/fast-light/fastaop/tree/master/fastaop/src/main/java/org/fastlight/aop/util"

    %% Click Events for FastAPT Annotation Processing
    click AP "https://github.com/fast-light/fastaop/tree/master/fastapt/src/main/java/org/fastlight/apt/processor"
    click M "https://github.com/fast-light/fastaop/tree/master/fastapt/src/main/java/org/fastlight/apt/model"
    click CM "https://github.com/fast-light/fastaop/tree/master/fastapt/src/main/java/org/fastlight/apt/model/compile"
    click AT "https://github.com/fast-light/fastaop/tree/master/fastapt/src/main/java/org/fastlight/apt/translator"
    click AU "https://github.com/fast-light/fastaop/tree/master/fastapt/src/main/java/org/fastlight/apt/util"

    %% Click Event for Example Module
    click E "https://github.com/fast-light/fastaop/tree/master/example/src/main/java/org/fastlight/fastaop/example"
```
