# analogj/gitmask architecture

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

- Interactive diagram: https://gitdiagram.com/analogj/gitmask
- Repository: https://github.com/analogj/gitmask

## Overview

##### Project Type and Purpose
- Gitmask is an open-source, serverless service (AWS Lambda + API Gateway) that provides a custom “git remote” for anonymous contributions.
- It intercepts standard Git HTTP operations, strips identifying metadata (author, email, timestamps), squashes commits, and forwards them as pull requests to GitHub via the GitHub REST API.

##### File Structure
- Top-level artifacts:
- serverless.yml → defines AWS Lambda functions & HTTP endpoints
- Pipfile / setup.py → Python runtime dependencies
- package.json → Node.js/Serverless Framework dependencies
- .circleci/config.yml → CI pipeline
- “gitmask/” directory:
- git-info-refs.py & git-receive-pack.py → Lambda entrypoints handling `info/refs` and `receive-pack` requests
- lib/common → protocol parsing, string utilities
- lib/scm → GitHub backend adapter, refs container, repo utilities
- lib/gitmask_protocol & gitmask_receive_pack_handler → core logic for stripping metadata and packing commits
- No persistent storage shown; all state is transient in Lambdas and via GitHub API.

##### README for Insights
- Confirms AWS Lambda (Python) + Serverless Framework (Node.js)
- Requires environment variables for GitHub credentials and service naming
- CI/CD with CircleCI to run tests, install dependencies, and deploy (`sls deploy`)
- Local dev via `sls offline`

a. Main Components
- Developer’s Git Client
- AWS API Gateway
- Two Lambda Functions:
- InfoRefsHandler
- ReceivePackHandler
- Shared Python Libraries (gitmask/lib)
- GitHub REST API (external service)
- CI/CD Pipeline (CircleCI + Serverless Framework)
b. Relationships & Data Flows
1. Git client → HTTP(S) push or fetch to custom remote URL
2. API Gateway routes requests by path:
- `/v1/<owner>/<repo>/info/refs` → InfoRefsHandler
- `/v1/<owner>/<repo>/git-receive-pack` → ReceivePackHandler
3. Lambda handler loads common libraries, parses Git packfiles, strips PII.
4. ReceivePackHandler invokes GitHub API to create a squash‐merge pull request.
5. Lambda returns HTTP response (packfile negotiation or push confirmation).
6. CircleCI listens for gitmask repo changes → runs tests → triggers `sls deploy` to AWS.
c. Architectural Patterns
- Event-driven, micro-service (each Git protocol endpoint is a separate Lambda)
- Modular library layering: protocol parsing, SCM adapters, utility modules
- Infrastructure as Code (Serverless Framework defines resources in serverless.yml)
d. Key Technologies / Frameworks
- AWS API Gateway & AWS Lambda (Python 3.x)
- Serverless Framework (Node.js tooling)
- Python (pipenv, setup.py) for business logic
- Git HTTP protocol (custom parsing)
- GitHub REST API for PR creation
- CircleCI for automated testing & deployments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer
    Developer["Git Client"]:::dev

    %% AWS Cloud
    subgraph "AWS Cloud"
        API["API Gateway\n(v1 owner repo paths)"]:::aws
        InfoRefsHandler["InfoRefsHandler"]:::aws
        ReceivePackHandler["ReceivePackHandler"]:::aws
    end

    %% Shared Libraries
    subgraph "Shared Libraries" 
        ProtocolParsing["Protocol Parsing Library"]:::lib
        StringUtils["String Utilities Library"]:::lib
        ProtocolCore["Gitmask Protocol Core Logic"]:::lib
        ReceiveCore["Receive Pack Handling Core Logic"]:::lib
        GitHubAdapter["GitHub Backend Adapter"]:::lib
        GitHubRefs["GitHub Refs Container"]:::lib
        GitHubRepo["GitHub Repository Utilities"]:::lib
        GitHubUtils["GitHub Utility Functions"]:::lib
    end

    %% External Services
    GitHubAPI["GitHub REST API"]:::ext

    %% CI/CD & Infra as Code
    subgraph "CI/CD & Deployment"
        CircleCI["CircleCI"]:::cicd
        ConfigCI[".circleci/config.yml"]:::cicd
        ServerlessCFG["serverless.yml"]:::cicd
        PackageJSON["package.json"]:::cicd
        PipDeps["Pipfile & setup.py"]:::cicd
    end

    %% Flows
    Developer -->|HTTPS Git Fetch/Push| API
    API -->|Route /info/refs| InfoRefsHandler
    API -->|Route /git-receive-pack| ReceivePackHandler

    InfoRefsHandler -->|uses| ProtocolParsing
    InfoRefsHandler -->|uses| StringUtils
    InfoRefsHandler -->|uses| ProtocolCore

    ReceivePackHandler -->|uses| ProtocolParsing
    ReceivePackHandler -->|uses| StringUtils
    ReceivePackHandler -->|uses| ReceiveCore
    ReceivePackHandler -->|uses| GitHubAdapter
    GitHubAdapter -->|uses| GitHubRefs
    GitHubAdapter -->|uses| GitHubRepo
    GitHubAdapter -->|uses| GitHubUtils
    ReceivePackHandler -->|calls REST| GitHubAPI

    ReceivePackHandler -->|returns HTTP response| Developer
    InfoRefsHandler -->|returns HTTP response| Developer

    %% CI/CD Flow
    CircleCI -->|reads| ConfigCI
    CircleCI -->|runs tests & deploy| ServerlessCFG
    CircleCI -->|uses| PackageJSON
    CircleCI -->|uses| PipDeps
    CircleCI -.->|deploy via sls deploy| API
    CircleCI -.->|deploy via sls deploy| InfoRefsHandler
    CircleCI -.->|deploy via sls deploy| ReceivePackHandler

    %% Click Events
    click InfoRefsHandler "https://github.com/analogj/gitmask/blob/master/gitmask/git-info-refs.py"
    click ReceivePackHandler "https://github.com/analogj/gitmask/blob/master/gitmask/git-receive-pack.py"
    click ProtocolParsing "https://github.com/analogj/gitmask/blob/master/gitmask/lib/common/git.py"
    click StringUtils "https://github.com/analogj/gitmask/blob/master/gitmask/lib/common/string.py"
    click ProtocolCore "https://github.com/analogj/gitmask/blob/master/gitmask/lib/gitmask_protocol.py"
    click ReceiveCore "https://github.com/analogj/gitmask/blob/master/gitmask/lib/gitmask_receive_pack_handler.py"
    click GitHubAdapter "https://github.com/analogj/gitmask/blob/master/gitmask/lib/scm/github_backend.py"
    click GitHubRefs "https://github.com/analogj/gitmask/blob/master/gitmask/lib/scm/github_refs_container.py"
    click GitHubRepo "https://github.com/analogj/gitmask/blob/master/gitmask/lib/scm/github_repo.py"
    click GitHubUtils "https://github.com/analogj/gitmask/blob/master/gitmask/lib/scm/github_utils.py"
    click ServerlessCFG "https://github.com/analogj/gitmask/blob/master/serverless.yml"
    click ConfigCI "https://github.com/analogj/gitmask/blob/master/.circleci/config.yml"
    click PipDeps "https://github.com/analogj/gitmask/tree/master/Pipfile"
    click PipDeps "https://github.com/analogj/gitmask/blob/master/setup.py"

    %% Styles
    classDef aws fill:#e0ffe0,stroke:#2d662d;
    classDef dev fill:#e0f0ff,stroke:#2d3b66;
    classDef ext fill:#ffe0e0,stroke:#662d2d;
    classDef cicd fill:#ffffc0,stroke:#66662d;
    classDef lib fill:#f0f0f0,stroke:#666666;
```
