# rameshmf/sagan architecture

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

- Interactive diagram: https://gitdiagram.com/rameshmf/sagan
- Repository: https://github.com/rameshmf/sagan

## Overview

##### Main Components Identification
The system consists of three main components:
- sagan-site (Main web application)
- sagan-renderer (Content rendering service)
- sagan-client (Frontend assets)

##### Architecture Overview

a. Client Layer:
- Web Browsers
- API Consumers

b. Frontend Layer (sagan-client):
- JavaScript modules (admin.js, blog.js, etc.)
- CSS/SCSS styles
- Static assets (fonts, images)

c. Application Layer (sagan-site):
- Web Controllers
- Service Layer
- Domain Model
- Data Access Layer

d. Rendering Service (sagan-renderer):
- Asciidoctor/Markdown rendering
- Guide content processing
- GitHub integration

e. External Services:
- GitHub API
- Google Calendar API
- Redis Cache
- Database
- Elasticsearch

##### Component Relationships
- HTTP/HTTPS traffic between clients and the application
- REST API calls between sagan-site and sagan-renderer
- Database access patterns
- Cache interactions
- External API communications

##### Key Subsystems
Major functional areas:
- Blog System
- Guides Management
- Team Management
- Project Information
- Events Calendar
- Content Rendering

##### Infrastructure Components
Include:
- Concourse CI/CD pipeline
- Redis caching layer
- Elasticsearch search engine
- Database system
- Static asset serving

##### Specific Implementation Details
Specialized components:
- Security configuration
- MVC configuration
- Template engine (Thymeleaf)
- URL rewriting
- Webhook handlers

##### Data Flow Patterns
Illustrate:
- Content rendering workflow
- Guide processing pipeline
- Blog post creation/update flow
- Project metadata management
- Search indexing process

##### Security perimeters

- The separation between the main site and renderer service
- The role of caching in performance optimization
- Integration points with external services
- Content processing workflows
- API boundaries and contracts

Remember to:
- Use consistent notation
- Provide sufficient detail while maintaining clarity
- Annotations for key architectural decisions
- Both runtime and deployment perspectives

This system design should reflect Sagan's role as both a production website and a reference application, highlighting Spring best practices and patterns.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        WB[Web Browsers]:::client
        AC[API Consumers]:::client
    end

    subgraph "Frontend Layer"
        FA["Frontend Assets"]:::frontend
        JS["JavaScript Modules"]:::frontend
        CSS["CSS/SCSS Styles"]:::frontend
    end

    subgraph "Application Layer"
        WA["Main Web Application"]:::app
        
        subgraph "Core Components"
            SC["Security Config"]:::config
            MC["MVC Config"]:::config
            CC["Cache Config"]:::config
            DC["Database Config"]:::config
        end
        
        subgraph "Feature Modules"
            BS["Blog System"]:::module
            GM["Guides Management"]:::module
            TM["Team Management"]:::module
            PI["Project Information"]:::module
            EC["Events Calendar"]:::module
        end
    end

    subgraph "Rendering Service"
        RS["Content Renderer"]:::service
        CR["Content Rendering Components"]:::component
        GI["GitHub Integration"]:::component
    end

    subgraph "External Services"
        GH["GitHub API"]:::external
        GC["Google Calendar API"]:::external
        RC["Redis Cache"]:::datastore
        DB["Database"]:::datastore
        ES["Elasticsearch"]:::datastore
    end

    subgraph "Infrastructure"
        CD["CI/CD Pipeline"]:::infra
    end

    %% Relationships
    WB --> FA
    AC --> WA
    FA --> WA
    JS --> FA
    CSS --> FA
    WA --> RS
    RS --> CR
    RS --> GI
    GI --> GH
    WA --> RC
    WA --> DB
    WA --> ES
    WA --> GC
    BS --> DB
    GM --> DB
    TM --> DB
    PI --> DB
    EC --> GC

    %% Click Events
    click WA "https://github.com/RameshMF/sagan/tree/master/sagan-site"
    click RS "https://github.com/RameshMF/sagan/tree/master/sagan-renderer"
    click FA "https://github.com/RameshMF/sagan/tree/master/sagan-client"
    click BS "https://github.com/RameshMF/sagan/tree/master/sagan-site/src/main/java/sagan/site/blog"
    click GM "https://github.com/RameshMF/sagan/tree/master/sagan-site/src/main/java/sagan/site/guides"
    click TM "https://github.com/RameshMF/sagan/tree/master/sagan-site/src/main/java/sagan/site/team"
    click PI "https://github.com/RameshMF/sagan/tree/master/sagan-site/src/main/java/sagan/site/projects"
    click EC "https://github.com/RameshMF/sagan/tree/master/sagan-site/src/main/java/sagan/site/events"
    click CR "https://github.com/RameshMF/sagan/tree/master/sagan-renderer/src/main/java/sagan/renderer/markup"
    click SC "https://github.com/RameshMF/sagan/blob/master/sagan-site/src/main/java/sagan/SecurityConfig.java"
    click CC "https://github.com/RameshMF/sagan/blob/master/sagan-site/src/main/java/sagan/CacheConfig.java"
    click DC "https://github.com/RameshMF/sagan/blob/master/sagan-site/src/main/java/sagan/DatabaseConfig.java"
    click MC "https://github.com/RameshMF/sagan/blob/master/sagan-site/src/main/java/sagan/MvcConfig.java"
    click GI "https://github.com/RameshMF/sagan/tree/master/sagan-renderer/src/main/java/sagan/renderer/github"
    click JS "https://github.com/RameshMF/sagan/tree/master/sagan-client/src/app"
    click CSS "https://github.com/RameshMF/sagan/tree/master/sagan-client/src/css"
    click CD "https://github.com/RameshMF/sagan/tree/master/concourse"

    %% Styles
    classDef client fill:#B3E5FC,stroke:#0288D1
    classDef frontend fill:#C8E6C9,stroke:#388E3C
    classDef app fill:#E1BEE7,stroke:#7B1FA2
    classDef config fill:#FFE0B2,stroke:#F57C00
    classDef module fill:#F8BBD0,stroke:#C2185B
    classDef service fill:#B2DFDB,stroke:#00796B
    classDef component fill:#D1C4E9,stroke:#512DA8
    classDef external fill:#CFD8DC,stroke:#455A64
    classDef datastore fill:#FFECB3,stroke:#FFA000
    classDef infra fill:#FFCCBC,stroke:#E64A19
```
