# venkataravindra/url-shorten-project architecture

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

- Interactive diagram: https://gitdiagram.com/venkataravindra/url-shorten-project
- Repository: https://github.com/venkataravindra/url-shorten-project

## Overview

This is a Spring Boot platform that turns engineering requirements into reviewable software-workflow outputs, alongside a runnable URL-shortener application used both as product and brownfield baseline. Users create and execute DAG workflows, review artifacts at approval gates, then inspect decisions, audit history, summaries, and reliability metrics. The separate URL flow creates links, redirects visitors, and records click analytics. The README documents these capabilities; source excerpts chiefly show the browser console’s REST calls, so some backend connections are documented rather than source-verified.

Main entry points: [`src/main/java/com/example/agentic/service/WorkflowService.java`](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/service/WorkflowService.java) (Workflow service), [`src/main/java/com/example/agentic/urlshortener/service/UrlShortenerService.java`](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/UrlShortenerService.java) (Short-link service), [`src/main/resources/static/app.js`](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/resources/static/app.js) (Console UI), [`src/main/java/com/example/agentic/orchestration/WorkflowEngine.java`](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowEngine.java) (DAG engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Web console"]
  node_console_ui["Console UI<br/>[app.js]"]
  node_console_flows["Flow runner<br/>[flows.js]"]
end

subgraph group_workflow["Engineering workflow"]
  node_workflow_api["Workflow API"]
  node_workflow_service["Workflow service"]
  node_workflow_engine["DAG engine"]
  node_scheduler["Task scheduler"]
  node_agents["Agent stages"]
  node_llm["LLM provider"]
  node_brownfield["Codebase analysis"]
end

subgraph group_governance["Governance and observability"]
  node_governance_services["Approval and policy"]
  node_artifact_service["Artifacts and decisions"]
  node_audit["Audit trail<br/>[AuditService.java]"]
  node_metrics["Reliability metrics"]
  node_workflow_store[("Workflow state store")]
end

subgraph group_shortener["URL shortener"]
  node_url_api["URL API"]
  node_url_service["Short-link service"]
  node_url_writer["Link writer"]
  node_url_validation["URL validation<br/>[UrlValidator.java]"]
  node_url_store[("Link and click data")]
end

node_engineer(("Engineer / approver"))

node_engineer -->|"uses"| node_console_ui
node_console_ui -->|"calls REST"| node_workflow_api
node_console_ui -->|"calls REST"| node_url_api
node_console_flows -->|"runs API flows"| node_workflow_api
node_workflow_api -.->|"handles requests"| node_workflow_service
node_workflow_service -.->|"executes workflow"| node_workflow_engine
node_workflow_engine -->|"schedules tasks"| node_scheduler
node_scheduler -->|"dispatches stages"| node_agents
node_agents -->|"requests outputs"| node_llm
node_agents -->|"scans baseline"| node_brownfield
node_workflow_engine -->|"enforces approval gates"| node_governance_services
node_governance_services -->|"persists workflow state"| node_workflow_store
node_workflow_service -.->|"serves outcomes"| node_artifact_service
node_workflow_service -->|"records events"| node_audit
node_metrics -->|"derives metrics"| node_workflow_store
node_url_api -.->|"handles link requests"| node_url_service
node_url_service -.->|"validates target"| node_url_validation
node_url_service -.->|"writes links"| node_url_writer
node_url_service -->|"reads clicks and links"| node_url_store

click node_console_ui "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/resources/static/app.js"
click node_console_flows "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/resources/static/flows.js"
click node_workflow_api "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/controller/WorkflowController.java"
click node_workflow_service "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/service/WorkflowService.java"
click node_workflow_engine "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowEngine.java"
click node_scheduler "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowScheduler.java"
click node_agents "https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/agent"
click node_llm "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/llm/MockLLMProvider.java"
click node_brownfield "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/codebase/CodebaseAnalyzer.java"
click node_governance_services "https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/governance"
click node_artifact_service "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/service/ArtifactService.java"
click node_audit "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/audit/AuditService.java"
click node_metrics "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/metrics/MetricsService.java"
click node_workflow_store "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowStateStore.java"
click node_url_api "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/controller/UrlShortenerController.java"
click node_url_service "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/UrlShortenerService.java"
click node_url_writer "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/ShortUrlWriter.java"
click node_url_validation "https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/UrlValidator.java"
click node_url_store "https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/urlshortener/repository"

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_console_ui,node_console_flows toneBlue
class node_workflow_api,node_workflow_service,node_workflow_engine,node_scheduler,node_agents,node_llm,node_brownfield toneAmber
class node_governance_services,node_artifact_service,node_audit,node_metrics,node_workflow_store toneMint
class node_url_api,node_url_service,node_url_writer,node_url_validation,node_url_store toneRose
class node_engineer toneIndigo
```

## Components

### Web console

- [Console UI](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/resources/static/app.js): `src/main/resources/static/app.js`
- [Flow runner](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/resources/static/flows.js): `src/main/resources/static/flows.js`

### Engineering workflow

- [Workflow API](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/controller/WorkflowController.java): `src/main/java/com/example/agentic/controller/WorkflowController.java`
- [Workflow service](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/service/WorkflowService.java): `src/main/java/com/example/agentic/service/WorkflowService.java`
- [DAG engine](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowEngine.java): `src/main/java/com/example/agentic/orchestration/WorkflowEngine.java`
- [Task scheduler](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowScheduler.java): `src/main/java/com/example/agentic/orchestration/WorkflowScheduler.java`
- [Agent stages](https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/agent): `src/main/java/com/example/agentic/agent`
- [LLM provider](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/llm/MockLLMProvider.java): `src/main/java/com/example/agentic/llm/MockLLMProvider.java`
- [Codebase analysis](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/codebase/CodebaseAnalyzer.java): `src/main/java/com/example/agentic/codebase/CodebaseAnalyzer.java`

### Governance and observability

- [Approval and policy](https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/governance): `src/main/java/com/example/agentic/governance`
- [Artifacts and decisions](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/service/ArtifactService.java): `src/main/java/com/example/agentic/service/ArtifactService.java`
- [Audit trail](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/audit/AuditService.java): `src/main/java/com/example/agentic/audit/AuditService.java`
- [Reliability metrics](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/metrics/MetricsService.java): `src/main/java/com/example/agentic/metrics/MetricsService.java`
- [Workflow state store](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/orchestration/WorkflowStateStore.java): `src/main/java/com/example/agentic/orchestration/WorkflowStateStore.java`

### URL shortener

- [URL API](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/controller/UrlShortenerController.java): `src/main/java/com/example/agentic/urlshortener/controller/UrlShortenerController.java`
- [Short-link service](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/UrlShortenerService.java): `src/main/java/com/example/agentic/urlshortener/service/UrlShortenerService.java`
- [Link writer](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/ShortUrlWriter.java): `src/main/java/com/example/agentic/urlshortener/service/ShortUrlWriter.java`
- [URL validation](https://github.com/venkataravindra/url-shorten-project/blob/main/src/main/java/com/example/agentic/urlshortener/service/UrlValidator.java): `src/main/java/com/example/agentic/urlshortener/service/UrlValidator.java`
- [Link and click data](https://github.com/venkataravindra/url-shorten-project/tree/main/src/main/java/com/example/agentic/urlshortener/repository): `src/main/java/com/example/agentic/urlshortener/repository`

### Other components

- **Engineer / approver**

## Connections

- Engineer / approver → Console UI: uses (evidence: `README.md`)
- Console UI → Workflow API: calls REST (evidence: `src/main/resources/static/app.js`)
- Console UI → URL API: calls REST (evidence: `src/main/resources/static/app.js`)
- Flow runner → Workflow API: runs API flows (evidence: `src/main/resources/static/flows.js`)
- Workflow API → Workflow service: handles requests
- Workflow service → DAG engine: executes workflow
- DAG engine → Task scheduler: schedules tasks (evidence: `README.md`)
- Task scheduler → Agent stages: dispatches stages (evidence: `README.md`)
- Agent stages → LLM provider: requests outputs (evidence: `README.md`)
- Agent stages → Codebase analysis: scans baseline (evidence: `README.md`)
- DAG engine → Approval and policy: enforces approval gates (evidence: `README.md`)
- Approval and policy → Workflow state store: persists workflow state (evidence: `README.md`)
- Workflow service → Artifacts and decisions: serves outcomes
- Workflow service → Audit trail: records events (evidence: `README.md`)
- Reliability metrics → Workflow state store: derives metrics (evidence: `README.md`)
- URL API → Short-link service: handles link requests
- Short-link service → URL validation: validates target
- Short-link service → Link writer: writes links
- Short-link service → Link and click data: reads clicks and links (evidence: `README.md`)