# anaru03/cps-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/anaru03/cps-analyzer
- Repository: https://github.com/anaru03/cps-analyzer

## Overview

#### Purpose and entry points
Cps-analyzer is a Java 17 compiler-front-end exercise for Compiscript: it performs lexical and syntactic analysis, reports structured errors, and exposes both CLI and HTTP-facing entry points. Maven builds the project and invokes ANTLR 4 code generation from `src/main/antlr4/gt/edu/uvg/compiscript/Compiscript.g4`.

Primary launch classes are `src/main/java/gt/edu/uvg/compiscript/CompiscriptApplication.java` for the application/API runtime and `src/main/java/gt/edu/uvg/compiscript/cli/Main.java` for file-oriented command-line analysis.

#### Language definition and generated parser boundary
The Compiscript grammar is the authoritative language contract: `src/main/antlr4/gt/edu/uvg/compiscript/Compiscript.g4`. ANTLR-generated lexer/parser artifacts are an implementation boundary between grammar specification and handwritten analysis adapters.

A duplicate top-level grammar, `Gramática de Compiscript.g4`, and language definition document, `Definición de Compiscript.md`, provide source/reference context, but the Maven-standard grammar path is the likely build input.

#### Lexical analysis stage
`src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java` wraps the ANTLR lexer into a domain API. It consumes source text and produces recognized-token and lexical-error results through `ResultadoLexico.java` and `TokenReconocido.java`.

ANTLR failures are captured rather than leaked directly through `EscuchadorErroresLexicos.java` and represented as `ErrorLexico.java`. This isolates parser/API/CLI callers from ANTLR listener types and provides a stable diagnostic model.

#### Syntactic analysis stage
`src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java` drives parsing over the token stream produced from Compiscript input. It returns `ResultadoSintactico.java` and captures parser diagnostics as `ErrorSintactico.java`.

`EscuchadorErroresSintacticos.java` and `EstrategiaErroresSintacticos.java` define the parser error-handling boundary: custom listening and recovery behavior can collect multiple useful errors rather than relying on default ANTLR console output or fail-fast semantics.

#### Analysis orchestration and HTTP boundary
`src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java` is the application-level coordinator: it should sequence lexical and syntactic analysis and consolidate outcomes. `src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java` adapts that capability to an HTTP API.

The API contract is isolated in DTOs: request input in `dto/SolicitudAnalisis.java`, aggregate response in `dto/RespuestaAnalisis.java`, and externally serializable diagnostics in `dto/ErrorAnalisis.java`. This keeps transport payloads independent of lexer/parser domain classes.

#### Input/output flow
Source reaches the system either as a `.cps` file through `cli/Main.java` or as request content through `api/AnalisisController.java`. Both routes converge on analysis logic, then pass through lexer tokenization and parser validation. Results return recognized tokens and/or diagnostics, with error location/category information translated into domain or API DTOs.

Example inputs establish expected success and failure modes: `ejemplos/archivo_correcto.cps`, `ejemplos/error_lexico1.cps`, and `ejemplos/error_parser1.cps`.

#### Runtime and infrastructure
The backend runtime is Java 17 with Maven and ANTLR 4, configured by `pom.xml`. The presence of `CompiscriptApplication.java`, controller, and service indicates a Spring-style HTTP application layer.

A separate Vite/Vue frontend exists under `frontend/src/App.vue` and `frontend/src/main.js`. Its integration contract is the backend analysis API, though no deployment or proxy configuration is evident from the supplied tree.

Main entry points: [`src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java`](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java) (Analysis Service), [`src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java`](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java) (Lexical Analyzer), [`src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java`](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java) (Syntactic Analyzer), [`src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java`](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java) (Analysis Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Toolchain"]
  node_grammar["Compiscript Grammar<br/>ANTLR grammar<br/>[Compiscript.g4]"]
  node_antlr["Generated Lexer &amp; Parser<br/>ANTLR artifacts"]
  node_maven["Maven Build<br/>Java 17 build<br/>[pom.xml]"]
end

subgraph group_backend["Java Analysis Backend"]
  node_lexical["Lexical Analyzer<br/>lexer adapter"]
  node_lexical_result["Lexical Result<br/>domain result"]
  node_lexical_errors["Lexical Error Boundary<br/>error listener"]
  node_syntactic["Syntactic Analyzer<br/>parser adapter"]
  node_syntactic_result["Syntactic Result<br/>domain result"]
  node_syntax_errors["Syntax Error Boundary<br/>listener and recovery"]
end

subgraph group_api["HTTP API"]
  node_analysis_service["Analysis Service<br/>application service"]
  node_analysis_controller["Analysis Controller<br/>HTTP controller"]
  node_api_dtos["Analysis DTOs<br/>API contract"]
  node_application{{"Application Runtime<br/>Spring application"}}
end

subgraph group_clients["Clients"]
  node_cli{{"CLI<br/>command entry point<br/>[Main.java]"}}
  node_frontend["Vue Frontend<br/>Vite/Vue client<br/>[App.vue]"]
  node_examples["Example .cps Inputs<br/>sample source"]
end

node_maven -->|"generates from"| node_grammar
node_grammar -->|"defines"| node_antlr
node_antlr -->|"lexer runtime"| node_lexical
node_antlr -->|"parser runtime"| node_syntactic
node_lexical -->|"captures failures"| node_lexical_errors
node_lexical -->|"returns"| node_lexical_result
node_lexical -->|"token stream"| node_syntactic
node_syntactic -->|"captures and recovers"| node_syntax_errors
node_syntactic -->|"returns"| node_syntactic_result
node_analysis_service -->|"runs first"| node_lexical
node_analysis_service -->|"runs validation"| node_syntactic
node_analysis_controller -->|"delegates"| node_analysis_service
node_analysis_controller -->|"maps transport"| node_api_dtos
node_application -->|"hosts"| node_analysis_controller
node_cli -->|"submits file source"| node_analysis_service
node_frontend -->|"analysis requests"| node_analysis_controller
node_examples -.->|"input cases"| node_cli
node_lexical_result -->|"consolidated"| node_analysis_service
node_syntactic_result -->|"consolidated"| node_analysis_service
node_analysis_service -->|"response diagnostics"| node_api_dtos

click node_grammar "https://github.com/anaru03/cps-analyzer/blob/main/src/main/antlr4/gt/edu/uvg/compiscript/Compiscript.g4"
click node_lexical "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java"
click node_lexical_result "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/ResultadoLexico.java"
click node_lexical_errors "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/EscuchadorErroresLexicos.java"
click node_syntactic "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java"
click node_syntactic_result "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/ResultadoSintactico.java"
click node_syntax_errors "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/EscuchadorErroresSintacticos.java"
click node_analysis_service "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java"
click node_analysis_controller "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java"
click node_api_dtos "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/dto/SolicitudAnalisis.java"
click node_application "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/CompiscriptApplication.java"
click node_cli "https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/cli/Main.java"
click node_frontend "https://github.com/anaru03/cps-analyzer/blob/main/frontend/src/App.vue"
click node_examples "https://github.com/anaru03/cps-analyzer/blob/main/ejemplos/archivo_correcto.cps"
click node_maven "https://github.com/anaru03/cps-analyzer/blob/main/pom.xml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_grammar,node_antlr,node_maven toneBlue
class node_lexical,node_lexical_result,node_lexical_errors,node_syntactic,node_syntactic_result,node_syntax_errors toneAmber
class node_analysis_service,node_analysis_controller,node_api_dtos,node_application toneMint
class node_cli,node_frontend,node_examples toneRose
```

## Components

### Language Toolchain

- [Compiscript Grammar](https://github.com/anaru03/cps-analyzer/blob/main/src/main/antlr4/gt/edu/uvg/compiscript/Compiscript.g4): ANTLR grammar · Authoritative language contract and Maven generation input. · `src/main/antlr4/gt/edu/uvg/compiscript/Compiscript.g4`
- **Generated Lexer & Parser**: ANTLR artifacts · Generated boundary consumed by handwritten adapters.
- [Maven Build](https://github.com/anaru03/cps-analyzer/blob/main/pom.xml): Java 17 build · Configures ANTLR generation and backend build. · `pom.xml`

### Java Analysis Backend

- [Lexical Analyzer](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java): lexer adapter · `src/main/java/gt/edu/uvg/compiscript/lexer/AnalizadorLexico.java`
- [Lexical Result](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/ResultadoLexico.java): domain result · Recognized tokens and lexical diagnostics. · `src/main/java/gt/edu/uvg/compiscript/lexer/ResultadoLexico.java`
- [Lexical Error Boundary](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/lexer/EscuchadorErroresLexicos.java): error listener · Captures ANTLR lexer failures as domain errors. · `src/main/java/gt/edu/uvg/compiscript/lexer/EscuchadorErroresLexicos.java`
- [Syntactic Analyzer](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java): parser adapter · `src/main/java/gt/edu/uvg/compiscript/parser/AnalizadorSintactico.java`
- [Syntactic Result](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/ResultadoSintactico.java): domain result · Parsing outcome and syntax diagnostics. · `src/main/java/gt/edu/uvg/compiscript/parser/ResultadoSintactico.java`
- [Syntax Error Boundary](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/parser/EscuchadorErroresSintacticos.java): listener and recovery · Collects multiple parser errors with custom recovery. · `src/main/java/gt/edu/uvg/compiscript/parser/EscuchadorErroresSintacticos.java`

### HTTP API

- [Analysis Service](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java): application service · Sequences lexical and syntactic analysis and consolidates outcomes. · `src/main/java/gt/edu/uvg/compiscript/api/AnalisisService.java`
- [Analysis Controller](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java): HTTP controller · `src/main/java/gt/edu/uvg/compiscript/api/AnalisisController.java`
- [Analysis DTOs](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/api/dto/SolicitudAnalisis.java): API contract · Request, aggregate response, and serializable diagnostics. · `src/main/java/gt/edu/uvg/compiscript/api/dto/SolicitudAnalisis.java`
- [Application Runtime](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/CompiscriptApplication.java): Spring application · `src/main/java/gt/edu/uvg/compiscript/CompiscriptApplication.java`

### Clients

- [CLI](https://github.com/anaru03/cps-analyzer/blob/main/src/main/java/gt/edu/uvg/compiscript/cli/Main.java): command entry point · Analyzes .cps files. · `src/main/java/gt/edu/uvg/compiscript/cli/Main.java`
- [Vue Frontend](https://github.com/anaru03/cps-analyzer/blob/main/frontend/src/App.vue): Vite/Vue client · Consumes the backend analysis API. · `frontend/src/App.vue`
- [Example .cps Inputs](https://github.com/anaru03/cps-analyzer/blob/main/ejemplos/archivo_correcto.cps): sample source · Success and lexical or parser failure cases. · `ejemplos/archivo_correcto.cps`

## Connections

- Maven Build → Compiscript Grammar: generates from
- Compiscript Grammar → Generated Lexer & Parser: defines
- Generated Lexer & Parser → Lexical Analyzer: lexer runtime
- Generated Lexer & Parser → Syntactic Analyzer: parser runtime
- Lexical Analyzer → Lexical Error Boundary: captures failures
- Lexical Analyzer → Lexical Result: returns
- Lexical Analyzer → Syntactic Analyzer: token stream
- Syntactic Analyzer → Syntax Error Boundary: captures and recovers
- Syntactic Analyzer → Syntactic Result: returns
- Analysis Service → Lexical Analyzer: runs first
- Analysis Service → Syntactic Analyzer: runs validation
- Analysis Controller → Analysis Service: delegates
- Analysis Controller → Analysis DTOs: maps transport
- Application Runtime → Analysis Controller: hosts
- CLI → Analysis Service: submits file source
- Vue Frontend → Analysis Controller: analysis requests
- Example .cps Inputs → CLI: input cases
- Lexical Result → Analysis Service: consolidated
- Syntactic Result → Analysis Service: consolidated
- Analysis Service → Analysis DTOs: response diagnostics