# amine-lg/lineage architecture

> Architecture diagram of the GitHub repository amine-lg/lineage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amine-lg/lineage
- Repository: https://github.com/amine-lg/lineage

## Overview

1. **What this repository is**
   - Lineage is a read-only OpenShift access explainer. Its core job is to turn cluster authorization objects into an explainable relationship graph: who can do what, where, and through which chain of bindings, groups, SCCs, and image relationships.

2. **Top-level runtime shape**
   - The app has two primary entry paths: a local Python process (`run.py`, `lineage/__main__.py`, `lineage/cli.py`) and an in-cluster deployment built from `Containerfile` plus the `deploy/openshift/` manifests.
   - It supports three modes: mock data, local real-cluster access via the current `oc login` context, and in-cluster execution under a dedicated ServiceAccount.

3. **Cluster access boundary**
   - `lineage/cluster.py` is the main boundary to the OpenShift API and auth checks. The README makes clear the app is intentionally read-only and relies on `get`, `list`, and `oc auth can-i`.
   - This boundary is where the app reads cluster state such as Users, Identities, Groups, ServiceAccounts, RoleBindings, ClusterRoleBindings, SCCs, namespaces, workloads, ImageStreams, and images.

4. **Core analysis engine**
   - `lineage/engine/` is the analytical heart of the repo. Its modules are split by concern:
     - `_rbac` for RBAC relationships,
     - `_scc` for SecurityContextConstraints,
     - `_images` for image pull/push and image-stream relationships,
     - `_ghosts`, `_resurrectable`, and `_identity_audit` for stale, missing, or re-creatable references,
     - `_who_can` and `_classify` for reachability and labeling,
     - `_constants` for shared rules and thresholds.
   - This layer converts raw cluster objects into derived findings and lineage paths.

5. **Data and domain shaping**
   - `lineage/data.py`, `lineage/classifier.py`, and `lineage/openshift/shapes.py` define the repository’s domain vocabulary and normalization rules.
   - These pieces help the engine treat OpenShift-specific objects consistently, especially for object identity, subject kinds, and the “live vs dormant vs resurrectable” distinctions used throughout the UI.

6. **Derived findings and special cases**
   - The repository does more than show direct grants. It explicitly models:
     - ghost bindings for missing users/groups/ServiceAccounts,
     - latent/phantom/stranded/orphan identity states,
     - resurrectable ServiceAccount and namespace-based SCC access,
     - future SCC targets where RBAC grants reference an SCC name that does not yet exist.
   - These are treated as review signals and are separated from ordinary live access.

7. **UI architecture**
   - Presentation is split between server-side templates in `lineage/templates/` and UI composition logic in `lineage/ui/`.
   - `lineage/ui/pages/` appears to organize page-level view models and page assembly for major screens such as home, identities, images, namespaces, permissions, SCCs, and subjects.
   - `lineage/ui/buckets.py`, `filters.py`, and `view_models.py` provide grouping, display filtering, and shape conversion for the rendered pages.

8. **Rendered pages and navigation**
   - The templates correspond closely to the app’s exploration model: home, setup, aggregated views, namespace detail, subject detail, role/clusterrole detail, SCC detail, who-can analysis, permission grants, images, and identity audit.
   - Shared partials like `_kind.html`, `_markers.html`, `_rule_cells.html`, and `_resurrectable_table.html` indicate the UI is built from reusable classification and evidence blocks rather than ad hoc pages.

9. **Static frontend assets**
   - `lineage/static/lineage.js` and `lineage/static/style.css` supply interactive behavior and styling, but the repo is not structured like a full SPA. The overall architecture is server-rendered with light client-side enhancement.

10. **Data sources and operational assumptions**
   - The app assumes OpenShift-shaped inputs, not generic Kubernetes. The README and docs emphasize that v1 is intentionally OpenShift-focused.
   - It also has an optional HTPasswd integration path, which affects identity completeness and degraded-visibility handling when the underlying user directory cannot be fully read.

11. **Deployment and platform integration**
   - `deploy/openshift/` contains the production path: namespace creation, RBAC, build config, optional HTPasswd RBAC, deployment, and route exposure.
   - This means the system can be run as a cluster-native read-only service with explicit permissions rather than requiring a locally authenticated operator session.

12. **Test and validation boundary**
   - `tests/` covers the engine, page behavior, sorting, degraded visibility, mock dataset behavior, and OpenShift-specific edge cases such as ghost lineage, SCC target detection, and resurrectable grants.
   - The test suite is part of the architecture: it verifies the correctness of derived lineage, not just HTTP rendering.

13. **Key architectural flow**
   - In practice the flow is: OpenShift cluster state and auth context in → cluster adapter and data normalization → engine analysis/classification → page/view-model assembly → templates and static assets out.
   - The repo’s main design goal is to keep the raw cluster read boundary separate from the analysis engine and from the presentation layer, so the explanations remain auditable and safe to run.

Main entry points: [`lineage/cluster.py`](https://github.com/amine-lg/lineage/blob/main/lineage/cluster.py) (Cluster API), [`lineage/main.py`](https://github.com/amine-lg/lineage/blob/main/lineage/main.py) (App core), [`lineage/ui/pages/__init__.py`](https://github.com/amine-lg/lineage/blob/main/lineage/ui/pages/__init__.py) (Page assembly), [`tests/test_engine.py`](https://github.com/amine-lg/lineage/blob/main/tests/test_engine.py) (Test suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_run_py["Run script<br/>entrypoint<br/>[run.py]"]
  node_pkg_main["Module entry<br/>entrypoint<br/>[__main__.py]"]
  node_cli["CLI<br/>command<br/>[cli.py]"]
  node_app_main["App core<br/>orchestrator<br/>[main.py]"]
end

subgraph group_analysis["Analysis"]
  node_cluster[("Cluster API<br/>openShift adapter<br/>[cluster.py]")]
  node_data["Domain data<br/>normalization<br/>[data.py]"]
  node_classifier["Classifier<br/>normalization<br/>[classifier.py]"]
  node_shapes["Shape rules<br/>openShift domain<br/>[shapes.py]"]
  node_rbac{{"RBAC graph<br/>analysis<br/>[_rbac.py]"}}
  node_scc{{"SCC analysis<br/>[_scc.py]"}}
  node_images{{"Image links<br/>analysis<br/>[_images.py]"}}
  node_ghosts{{"Ghosts<br/>analysis<br/>[_ghosts.py]"}}
  node_resurrect{{"Resurrectable<br/>analysis<br/>[_resurrectable.py]"}}
  node_audit{{"Identity audit<br/>analysis<br/>[_identity_audit.py]"}}
  node_who_can{{"Who-can<br/>analysis<br/>[_who_can.py]"}}
  node_classify_engine{{"Labeling<br/>analysis<br/>[_classify.py]"}}
end

subgraph group_presentation["Presentation"]
  node_pages["Page assembly<br/>ui composition<br/>[__init__.py]"]
  node_view_models["View models<br/>ui support<br/>[view_models.py]"]
  node_templates["Templates<br/>server-rendered UI<br/>[base.html]"]
  node_assets["Frontend assets<br/>static UI<br/>[lineage.js]"]
end

subgraph group_delivery["Delivery"]
  node_deploy["OpenShift deploy<br/>deployment<br/>[30-deployment.yaml]"]
  node_tests["Test suite<br/>validation<br/>[test_engine.py]"]
end

node_run_py -->|"launches"| node_cli
node_pkg_main -->|"dispatches"| node_cli
node_cli -->|"starts"| node_app_main
node_app_main -->|"reads"| node_cluster
node_app_main -->|"normalizes"| node_data
node_app_main -->|"labels"| node_classifier
node_app_main -->|"assembles"| node_pages
node_data -->|"adapts"| node_shapes
node_classifier -->|"feeds"| node_classify_engine
node_cluster -->|"supplies"| node_rbac
node_cluster -->|"supplies"| node_scc
node_cluster -->|"supplies"| node_images
node_cluster -->|"supplies"| node_ghosts
node_cluster -->|"supplies"| node_resurrect
node_cluster -->|"supplies"| node_audit
node_cluster -->|"queries"| node_who_can
node_rbac -->|"powers"| node_who_can
node_scc -->|"contributes"| node_resurrect
node_ghosts -->|"signals"| node_pages
node_audit -->|"signals"| node_pages
node_images -->|"renders"| node_pages
node_who_can -->|"renders"| node_pages
node_pages -->|"uses"| node_view_models
node_view_models -->|"renders"| node_templates
node_templates -->|"enhanced by"| node_assets
node_deploy -->|"runs in"| node_cluster
node_tests -->|"verifies"| node_app_main
node_tests -->|"verifies"| node_cluster
node_tests -->|"verifies"| node_rbac
node_tests -->|"verifies"| node_ghosts

click node_run_py "https://github.com/amine-lg/lineage/blob/main/run.py"
click node_pkg_main "https://github.com/amine-lg/lineage/blob/main/lineage/__main__.py"
click node_cli "https://github.com/amine-lg/lineage/blob/main/lineage/cli.py"
click node_app_main "https://github.com/amine-lg/lineage/blob/main/lineage/main.py"
click node_cluster "https://github.com/amine-lg/lineage/blob/main/lineage/cluster.py"
click node_data "https://github.com/amine-lg/lineage/blob/main/lineage/data.py"
click node_classifier "https://github.com/amine-lg/lineage/blob/main/lineage/classifier.py"
click node_shapes "https://github.com/amine-lg/lineage/blob/main/lineage/openshift/shapes.py"
click node_rbac "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_rbac.py"
click node_scc "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_scc.py"
click node_images "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_images.py"
click node_ghosts "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_ghosts.py"
click node_resurrect "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_resurrectable.py"
click node_audit "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_identity_audit.py"
click node_who_can "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_who_can.py"
click node_classify_engine "https://github.com/amine-lg/lineage/blob/main/lineage/engine/_classify.py"
click node_pages "https://github.com/amine-lg/lineage/blob/main/lineage/ui/pages/__init__.py"
click node_view_models "https://github.com/amine-lg/lineage/blob/main/lineage/ui/view_models.py"
click node_templates "https://github.com/amine-lg/lineage/blob/main/lineage/templates/base.html"
click node_assets "https://github.com/amine-lg/lineage/blob/main/lineage/static/lineage.js"
click node_deploy "https://github.com/amine-lg/lineage/blob/main/deploy/openshift/30-deployment.yaml"
click node_tests "https://github.com/amine-lg/lineage/blob/main/tests/test_engine.py"

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_run_py,node_pkg_main,node_cli,node_app_main toneBlue
class node_cluster,node_data,node_classifier,node_shapes,node_rbac,node_scc,node_images,node_ghosts,node_resurrect,node_audit,node_who_can,node_classify_engine toneAmber
class node_pages,node_view_models,node_templates,node_assets toneMint
class node_deploy,node_tests toneRose
```

## Components

### Runtime

Local entrypoints and the in-cluster delivery path.

- [Run script](https://github.com/amine-lg/lineage/blob/main/run.py): entrypoint · Local process launcher. · `run.py`
- [Module entry](https://github.com/amine-lg/lineage/blob/main/lineage/__main__.py): entrypoint · Python package entrypoint. · `lineage/__main__.py`
- [CLI](https://github.com/amine-lg/lineage/blob/main/lineage/cli.py): command · Command-line interface and mode selection. · `lineage/cli.py`
- [App core](https://github.com/amine-lg/lineage/blob/main/lineage/main.py): orchestrator · High-level application flow and setup. · `lineage/main.py`

### Analysis

Cluster access, normalization, and lineage derivation.

- [Cluster API](https://github.com/amine-lg/lineage/blob/main/lineage/cluster.py): openShift adapter · Read-only boundary to OpenShift auth and objects. · `lineage/cluster.py`
- [Domain data](https://github.com/amine-lg/lineage/blob/main/lineage/data.py): normalization · Shared object vocabulary and identity shaping. · `lineage/data.py`
- [Classifier](https://github.com/amine-lg/lineage/blob/main/lineage/classifier.py): normalization · Object classification and state interpretation. · `lineage/classifier.py`
- [Shape rules](https://github.com/amine-lg/lineage/blob/main/lineage/openshift/shapes.py): openShift domain · OpenShift-specific shape and subject normalization. · `lineage/openshift/shapes.py`
- [RBAC graph](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_rbac.py): analysis · Role, binding, and subject relationship expansion. · `lineage/engine/_rbac.py`
- [SCC analysis](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_scc.py): analysis · SecurityContextConstraints reachability and grants. · `lineage/engine/_scc.py`
- [Image links](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_images.py): analysis · Image pull, push, and ImageStream relationships. · `lineage/engine/_images.py`
- [Ghosts](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_ghosts.py): analysis · Missing or stale subjects and bindings. · `lineage/engine/_ghosts.py`
- [Resurrectable](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_resurrectable.py): analysis · Latent access that can reappear from namespace or SA state. · `lineage/engine/_resurrectable.py`
- [Identity audit](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_identity_audit.py): analysis · Identity completeness and degraded-visibility checks. · `lineage/engine/_identity_audit.py`
- [Who-can](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_who_can.py): analysis · Reachability queries and permission discovery. · `lineage/engine/_who_can.py`
- [Labeling](https://github.com/amine-lg/lineage/blob/main/lineage/engine/_classify.py): analysis · Shared derived labels and classification helpers. · `lineage/engine/_classify.py`

### Presentation

Page assembly, templates, and light client-side behavior.

- [Page assembly](https://github.com/amine-lg/lineage/blob/main/lineage/ui/pages/__init__.py): ui composition · Page-level view models and screen assembly. · `lineage/ui/pages/__init__.py`
- [View models](https://github.com/amine-lg/lineage/blob/main/lineage/ui/view_models.py): ui support · Rendered display models and aggregation helpers. · `lineage/ui/view_models.py`
- [Templates](https://github.com/amine-lg/lineage/blob/main/lineage/templates/base.html): server-rendered UI · HTML templates for detail and overview pages. · `lineage/templates/base.html`
- [Frontend assets](https://github.com/amine-lg/lineage/blob/main/lineage/static/lineage.js): static UI · Lightweight client-side behavior and styling. · `lineage/static/lineage.js`

### Delivery

OpenShift manifests and validation coverage.

- [OpenShift deploy](https://github.com/amine-lg/lineage/blob/main/deploy/openshift/30-deployment.yaml): deployment · Namespace, RBAC, build, deployment, and route manifests. · `deploy/openshift/30-deployment.yaml`
- [Test suite](https://github.com/amine-lg/lineage/blob/main/tests/test_engine.py): validation · Behavioral coverage for engine, pages, and OpenShift edge cases. · `tests/test_engine.py`

## Connections

- Run script → CLI: launches · Local script hands control to the CLI.
- Module entry → CLI: dispatches · Package entrypoint routes into the CLI.
- CLI → App core: starts · CLI selects mode and starts the application.
- App core → Cluster API: reads · Core app creates the read-only cluster boundary.
- App core → Domain data: normalizes · Core app uses shared domain shaping.
- App core → Classifier: labels · Core app relies on object classification.
- App core → Page assembly: assembles · Core app builds page-level outputs.
- Domain data → Shape rules: adapts · Domain vocabulary is aligned to OpenShift shapes.
- Classifier → Labeling: feeds · Classification helpers support derived labels.
- Cluster API → RBAC graph: supplies · Cluster objects feed RBAC expansion.
- Cluster API → SCC analysis: supplies · Cluster objects feed SCC analysis.
- Cluster API → Image links: supplies · Cluster objects feed image relationship analysis.
- Cluster API → Ghosts: supplies · Cluster state is checked for missing references.
- Cluster API → Resurrectable: supplies · Cluster state is checked for latent access paths.
- Cluster API → Identity audit: supplies · Cluster state is checked for identity completeness.
- Cluster API → Who-can: queries · Auth context and objects support reachability queries.
- RBAC graph → Who-can: powers · RBAC relationships underpin who-can analysis.
- SCC analysis → Resurrectable: contributes · SCC grants can become resurrectable access.
- Ghosts → Page assembly: signals · Derived ghost states are surfaced in UI views.
- Identity audit → Page assembly: signals · Identity audit findings feed dedicated pages.
- Image links → Page assembly: renders · Image relationships are presented in image views.
- Who-can → Page assembly: renders · Permission reachability drives permission pages.
- Page assembly → View models: uses · Pages are assembled from shared view models.
- View models → Templates: renders · View models are rendered by server templates.
- Templates → Frontend assets: enhanced by · Templates are lightly enhanced by static assets.
- OpenShift deploy → Cluster API: runs in · OpenShift manifests provide the in-cluster execution path.
- Test suite → App core: verifies · Tests cover orchestration and mode selection.
- Test suite → Cluster API: verifies · Tests cover read-boundary and visibility behavior.
- Test suite → RBAC graph: verifies · Tests cover derived authorization relationships.
- Test suite → Ghosts: verifies · Tests cover ghost and missing-reference logic.
