# ashirrwad/paynow architecture

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

- Interactive diagram: https://gitdiagram.com/ashirrwad/paynow
- Repository: https://github.com/ashirrwad/paynow

## Overview

##### Project type and purpose
- This is a Spring Boot–based backend microservice (“PayNow Agent Assist”) that exposes a REST API for making AI-assisted payment decisions. It does not include a frontend in this repo; instead, it offers a well-documented HTTP API, persistence, rate limiting, security, metrics, and an “agent” orchestration layer that uses multiple asynchronous tools.

##### File structure
- Top-level /pom.xml, Dockerfile, README.md
- src/main/java/com/paynow/agentassist
- config (Spring configs: SecurityConfig, WebConfig, MetricsConfig, ApiKeyConfig, DataInitializer)
- controller (PaymentController, MetricsController)
- interceptor & filter (PerformanceInterceptor, RequestCachingFilter, ApiKeyAuthenticationFilter)
- service (core business: payment, metrics, rate limiting, risk assessment, agent orchestration & tools)
- strategy (DecisionStrategyRegistry + concrete strategies)
- repository (Spring Data for ApiKey, CustomerBalance, PaymentTransaction)
- entity/domain/dto (JPA entities, domain models, request/response builders)
- event (EventPublisher simulating a message bus)
- util (PiiMaskingUtil, PerformanceLogger, ResourceManager)
- src/main/resources/application*.yml (profiles)
- src/test covers integration and unit tests
- Docker & shell script for local testing

##### README for additional insights
- Describes asynchronous tool execution, performance monitoring (Micrometer), in-memory caching & DB, simulated event bus, security (API keys), observability (logs + Prometheus), agent tooling (balance, risk, case creation), retry/timeout guardrails, fallback strategy

##### Main components and interactions
a. API Layer
- PaymentController (POST /api/v1/payments/decide)
- MetricsController (/actuator/prometheus)
b. Security & Pre-processing
- ApiKeyAuthenticationFilter for header-based auth
- RateLimitingService invoked via filter/interceptor
- RequestCachingFilter, PerformanceInterceptor add caching & trace IDs
c. Service Layer
- PaymentDecisionService (impl + PerformanceMonitored decorator)
- Agent orchestration: PaymentDecisionAgent → PaymentDecisionProcessor
- Asynchronous tools (CompletableFuture): BalanceTool, RiskSignalsTool, CaseCreationTool
- Strategy pattern for representing decision logic (Aggressive, Conservative, Default)
d. Data Layer
- Spring Data JPA repositories → H2 in-memory database (ApiKeyEntity, CustomerBalance, PaymentTransaction)
e. Eventing & Observability
- EventPublisher logs “PaymentDecisionEvent” (simulated bus)
- Micrometer metrics via Actuator
- SLF4J + MDC trace IDs + PiiMaskingUtil
f. Config & Infrastructure
- application-local.yml / prod.yml profiles
- Dockerfile for containerization

##### Key architectural patterns & design principles
- MVC separation (Controller → Service → Repository)
- Strategy pattern for pluggable decision logic
- Factory (AgentToolFactory) for tool instantiation
- Decorator (PerformanceMonitoredPaymentDecisionService) for metrics
- Asynchronous parallel execution of I/O-bound tools
- Builder pattern for request/response DTOs
- Cross-cutting concerns handled by Spring Security filters & interceptors

- Notes on critical configuration (timeouts, retries, pool sizes)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        Client["HTTP Client / cURL"]:::external
    end

    %% API & Security Layer
    subgraph "API & Security"
        APIKeyFilter["ApiKeyAuthenticationFilter"]:::api
        RateLimiter["RateLimitingService"]:::api
        RequestCache["RequestCachingFilter"]:::api
        PerfInterceptor["PerformanceInterceptor"]:::api
    end

    %% Controllers Layer
    subgraph "Controllers"
        PaymentCtrl["PaymentController"]:::api
        MetricsCtrl["MetricsController"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        PaymentSvcIface["PaymentDecisionService (interface)"]:::service
        PaymentSvcImpl["PaymentDecisionServiceImpl"]:::service
        PerfMonSvc["PerformanceMonitoredPaymentDecisionService"]:::service
        Agent["PaymentDecisionAgent"]:::service
        Processor["PaymentDecisionProcessor"]:::service
    end

    %% Agent Tools & Strategy Layer
    subgraph "Agent Tools & Strategy"
        Factory["AgentToolFactory"]:::service
        BalanceTool["BalanceTool"]:::service
        RiskTool["RiskSignalsTool"]:::service
        CaseTool["CaseCreationTool"]:::service
        DSRegistry["DecisionStrategyRegistry"]:::service
        DefaultStrat["DefaultDecisionStrategy"]:::service
        AggressiveStrat["AggressiveDecisionStrategy"]:::service
        ConservativeStrat["ConservativeDecisionStrategy"]:::service
    end

    %% Data Access & Persistence Layer
    subgraph "Data Access & Persistence"
        ApiKeyRepo["ApiKeyRepository"]:::data
        BalanceRepo["CustomerBalanceRepository"]:::data
        TxRepo["PaymentTransactionRepository"]:::data
        H2["H2 Database"]:::external
    end

    %% Eventing & Observability Layer
    subgraph "Eventing & Observability"
        EventPub["EventPublisher"]:::external
        Event["PaymentDecisionEvent"]:::external
        Prometheus["Prometheus Endpoint"]:::external
        Logs["SLF4J + MDC Logs"]:::external
    end

    %% Config & Infrastructure Layer
    subgraph "Config & Infrastructure"
        SecurityCfg["SecurityConfig"]:::cross
        WebCfg["WebConfig"]:::cross
        MetricsCfg["MetricsConfig"]:::cross
        ApiKeyCfg["ApiKeyConfig"]:::cross
        DataInit["DataInitializer"]:::cross
        Profiles["application*.yml"]:::cross
        DockerfileNode["Dockerfile"]:::cross
    end

    %% Cross-Cutting Utilities
    subgraph "Cross-Cutting Utilities"
        PiiUtil["PiiMaskingUtil"]:::cross
        PerfLogger["PerformanceLogger"]:::cross
        ResourceManager["ResourceManager"]:::cross
    end

    %% Connections
    Client -->|HTTP Request| APIKeyFilter
    APIKeyFilter -->|validate key| RateLimiter
    RateLimiter -->|check rate| RequestCache
    RequestCache -->|cache request| PerfInterceptor
    PerfInterceptor -->|add trace ID| PaymentCtrl
    PaymentCtrl -->|invoke| PaymentSvcIface
    PaymentSvcIface -->|delegate| PaymentSvcImpl
    PaymentSvcImpl -->|decorate| PerfMonSvc
    PerfMonSvc -->|orchestrate| Agent
    Agent -->|execute| Processor
    Processor -->|async – CompletableFuture| BalanceTool
    Processor -->|async – CompletableFuture| RiskTool
    Processor -->|async – CompletableFuture| CaseTool
    BalanceTool -->|read/write| BalanceRepo
    RiskTool -->|external stub| RateLimiter
    CaseTool -->|write| TxRepo
    BalanceRepo -->|JPA| H2
    TxRepo -->|JPA| H2
    Processor -->|apply| DSRegistry
    DSRegistry --> DefaultStrat
    DSRegistry --> AggressiveStrat
    DSRegistry --> ConservativeStrat
    PerfMonSvc -->|publish| EventPub
    EventPub -->|emit| Event
    MetricsCtrl -->|expose| Prometheus
    PerfInterceptor -->|log| Logs

    %% Click Events
    click PaymentCtrl "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/controller/PaymentController.java"
    click MetricsCtrl "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/controller/MetricsController.java"
    click APIKeyFilter "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/security/ApiKeyAuthenticationFilter.java"
    click RateLimiter "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/RateLimitingService.java"
    click RequestCache "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/interceptor/RequestCachingFilter.java"
    click PerfInterceptor "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/interceptor/PerformanceInterceptor.java"
    click PaymentSvcIface "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/payment/PaymentDecisionService.java"
    click PaymentSvcImpl "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/payment/impl/PaymentDecisionServiceImpl.java"
    click PerfMonSvc "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/payment/impl/PerformanceMonitoredPaymentDecisionService.java"
    click Agent "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/agent/PaymentDecisionAgent.java"
    click Processor "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/agent/PaymentDecisionProcessor.java"
    click BalanceTool "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/agent/tool/BalanceTool.java"
    click RiskTool "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/agent/tool/RiskSignalsTool.java"
    click CaseTool "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/service/agent/tool/CaseCreationTool.java"
    click DSRegistry "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/strategy/DecisionStrategyRegistry.java"
    click DefaultStrat "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/strategy/DefaultDecisionStrategy.java"
    click AggressiveStrat "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/strategy/AggressiveDecisionStrategy.java"
    click ConservativeStrat "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/strategy/ConservativeDecisionStrategy.java"
    click ApiKeyRepo "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/repository/ApiKeyRepository.java"
    click BalanceRepo "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/repository/CustomerBalanceRepository.java"
    click TxRepo "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/repository/PaymentTransactionRepository.java"
    click EventPub "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/event/EventPublisher.java"
    click Event "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/event/PaymentDecisionEvent.java"
    click SecurityCfg "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/config/SecurityConfig.java"
    click WebCfg "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/config/WebConfig.java"
    click MetricsCfg "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/config/MetricsConfig.java"
    click ApiKeyCfg "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/config/ApiKeyConfig.java"
    click DataInit "https://github.com/ashirrwad/paynow/blob/main/src/main/java/com/paynow/agentassist/config/DataInitializer.java"
    click Profiles "https://github.com/ashirrwad/paynow/blob/main/src/main/resources/application.yml"
    click DockerfileNode "https://github.com/ashirrwad/paynow/tree/main/Dockerfile"

    %% Styles
    classDef api fill:#cfe2f3,stroke:#0366d6,color:#0366d6
    classDef service fill:#d9ead3,stroke:#38761d,color:#38761d
    classDef data fill:#f9cb9c,stroke:#e69138,color:#e69138
    classDef external fill:#e6e6e6,stroke:#767676,color:#333333
    classDef cross fill:#ead1dc,stroke:#b854a4,color:#b854a4
```
