# paduartesre/gitlab-aws architecture

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

- Interactive diagram: https://gitdiagram.com/paduartesre/gitlab-aws
- Repository: https://github.com/paduartesre/gitlab-aws

## Overview

##### Project type and purpose
- This is a serverless, event-driven automation system built in Terraform and Python.
- Its purpose is to automate GitLab repository lifecycle and CI/CD settings by collecting repository lists daily, comparing to the previous state, notifying on changes, and enforcing CI configuration rules via merge requests.

##### File structure
- Top-level Terraform definitions (main.tf, backend.tf, variables.tf) orchestrate the deployment.
- modules/ holds reusable Terraform modules for IAM roles, Lambda functions, SNS topics, and EventBridge schedules.
- lambdas/ contains the two Python functions (collector.py, configurator.py) plus their dependencies.

##### Key insights from README
- Two Lambda functions triggered daily by EventBridge Scheduler.
- Collector function: queries GitLab (token from Secrets Manager), compares to last list (in SSM Parameter Store), and publishes change notifications to an SNS topic.
- Configurator function: reads the stored list, inspects each repo’s CI/CD settings via GitLab API, and if misconfigured, removes the .gitlab-ci.yml, then opens a merge request to enforce settings.
- Terraform modules define IAM policies for least-privilege access, SNS topic for notifications, and EventBridge rule for scheduling.

- EventBridge Scheduler (cron rule)
- AWS Lambda:
- gitlab_repos_collector
- gitlab_ci_configurator
- AWS Secrets Manager (GitLab service-account token)
- AWS SSM Parameter Store (stored repo list)
- AWS SNS Topic (notification channel + subscription endpoints, e-mail)
- External GitLab API (target system)
- EventBridge → triggers → gitlab_repos_collector
- gitlab_repos_collector → reads token ← Secrets Manager
- gitlab_repos_collector → calls → GitLab API to list repos
- gitlab_repos_collector → compares → previous list in SSM Parameter Store
- gitlab_repos_collector → writes new list → SSM Parameter Store
- gitlab_repos_collector → publishes change events → SNS Topic → email subscribers
- EventBridge → triggers → gitlab_ci_configurator
- gitlab_ci_configurator → reads token ← Secrets Manager
- gitlab_ci_configurator → reads list ← SSM Parameter Store
- gitlab_ci_configurator → for each repo: GitLab API → inspect/remove .gitlab-ci.yml → create merge request if needed
c. Architectural patterns & design principles
- Serverless / event-driven design for cost-efficiency and scalability
- Least-privilege IAM roles scoped per Lambda module
- Infrastructure as code via Terraform modules for reusability and environment parity
- Use of managed services (Secrets Manager, SSM, SNS, EventBridge) to minimize operational overhead
d. Key technologies/frameworks
- AWS Lambda (Python runtime)
- Terraform (root configs + modules: iam, lambda, sns, eventbridge)
- AWS EventBridge Scheduler (daily cron)
- AWS SNS (notification fan-out)
- AWS Secrets Manager & Systems Manager Parameter Store
- GitLab API integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AWS Managed Services
    subgraph "AWS Managed Services"
        direction TB
        EventBridge["EventBridge Scheduler\n(cron)"]:::scheduling
        SecretsManager["Secrets Manager\n(GitLab Token)"]:::config
        SSM["SSM Parameter Store\n(Repo List)"]:::config
        SNS["SNS Topic\n(Change Notifications)"]:::messaging
    end

    %% Lambda Functions
    subgraph "AWS Lambda Functions"
        direction TB
        Collector["gitlab_repos_collector"]:::compute
        Configurator["gitlab_ci_configurator"]:::compute
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GitLabAPI["GitLab API"]:::external
    end

    %% Terraform Deployment
    subgraph "Terraform Deployment"
        direction TB
        EventBridgeModule["EventBridge Module"]:::deployment
        LambdaModule["Lambda Module"]:::deployment
        IAMModule["IAM Module"]:::deployment
        SNSModule["SNS Module"]:::deployment
        RootTF["Root Terraform Orchestration"]:::deployment
        Files["Supporting Artifacts"]:::deployment
        README["Project README"]:::deployment
    end

    %% Runtime Data Flows
    EventBridge -->|"triggers"| Collector
    EventBridge -->|"triggers"| Configurator
    Collector -->|"reads token"| SecretsManager
    Collector -->|"list repos"| GitLabAPI
    Collector -->|"get previous list"| SSM
    Collector -->|"store new list"| SSM
    Collector -->|"publish changes"| SNS
    SNS -->|"email subscribers"| SNS
    Configurator -->|"reads token"| SecretsManager
    Configurator -->|"reads repo list"| SSM
    Configurator -->|"inspect/remove CI file"| GitLabAPI
    Configurator -->|"create merge request"| GitLabAPI

    %% Deployment Links
    RootTF --> EventBridgeModule
    RootTF --> LambdaModule
    RootTF --> IAMModule
    RootTF --> SNSModule
    RootTF --> EventBridgeModule
    RootTF --> Files
    RootTF --> README

    %% Click Events
    click EventBridge "https://github.com/paduartesre/gitlab-aws/blob/main/modules/eventbridge/main.tf"
    click EventBridgeModule "https://github.com/paduartesre/gitlab-aws/blob/main/modules/eventbridge/main.tf"
    click LambdaModule "https://github.com/paduartesre/gitlab-aws/blob/main/modules/lambda/main.tf"
    click IAMModule "https://github.com/paduartesre/gitlab-aws/blob/main/modules/iam/main.tf"
    click SNSModule "https://github.com/paduartesre/gitlab-aws/blob/main/modules/sns/main.tf"
    click RootTF "https://github.com/paduartesre/gitlab-aws/blob/main/main.tf"
    click Files "https://github.com/paduartesre/gitlab-aws/tree/main/files/"
    click README "https://github.com/paduartesre/gitlab-aws/blob/main/README.md"
    click Collector "https://github.com/paduartesre/gitlab-aws/blob/main/lambdas/collector.py"
    click Configurator "https://github.com/paduartesre/gitlab-aws/blob/main/lambdas/configurator.py"
    click LambdaModule "https://github.com/paduartesre/gitlab-aws/blob/main/lambdas/requirements.txt"

    %% Styles
    classDef compute fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef messaging fill:#99ccff,stroke:#333,stroke-width:1px
    classDef config fill:#ccff99,stroke:#333,stroke-width:1px
    classDef scheduling fill:#ffdd99,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
    classDef deployment fill:#e0b3ff,stroke:#333,stroke-width:1px
```
