Service Catalog

What Is the Service Catalog?

CodeCargo uses machine learning, GenAI, and declarative code to automatically generate and maintain your Service Catalog. Teams no longer have to spend countless hours maintaining the Service Catalog - our platform does this for you giving you more time to actually build, test, and deploy your software.

Think of it as an automatically generated map of your software architecture that shows:

• What services exist in your codebase
• How components depend on each other
• Who owns and maintains each component
• Which CI/CD pipelines build, test, and deploy your code
• How your code is organized across repositories

Why Use the Service Catalog?

For New Team Members:

• Quickly understand your organization's architecture
• See how different services and components connect
• Identify who to talk to about specific components

For Architects & Technical Leads:

• Get a bird's-eye view of system architecture
• Identify architectural patterns and anti-patterns
• Spot tightly coupled components that might need refactoring
• Understand service boundaries and deployment patterns

For DevOps & Platform Engineers:

• See which components have CI/CD pipelines
• Understand deployment relationships
• Track infrastructure-as-code components
• Identify missing automation

For Engineering Managers:

• Understand team ownership boundaries
• See contribution patterns across repositories
• Identify knowledge silos or single points of failure

Accessing the Service Catalog

The Service Catalog is available at three levels, each providing different levels of detail:

Organization Level

View the complete architecture across your entire organization, including:

• All repositories
• All services and components
• All relationships and dependencies
• All owners and contributors

Best for: High-level architecture reviews, organization-wide planning, and cross-team coordination.

Project Level

See only the components and services within a specific project:

• Repositories belonging to the project
• Components within those repositories
• Relationships between project components

Best for: Project planning, team coordination, and understanding project-specific architecture.

Repository Level

Zoom in on a single repository:

• All components within the repository
• Internal dependencies
• External dependencies to other repositories
• CI/CD pipelines for this repository

Best for: Deep-diving into specific repositories, understanding component structure, and detailed dependency analysis.

How the Service Graph Is Created

The Service Catalog uses an intelligent multi-stage analysis pipeline that runs automatically. Here's what happens behind the scenes:

Stage 1: Component Discovery

The system scans your codebase looking for components by identifying common patterns:

Code Components:

• Projects with package managers (package.json, pom.xml, requirements.txt, etc.)
• Applications with specific frameworks
• Libraries and shared code

Infrastructure Components (IaC):

• Terraform configurations
• CloudFormation templates
• Kubernetes manifests
• Docker configurations

CI/CD Components:

• GitHub Actions workflows
• Jenkins pipelines
• Other automation scripts

For each component, the system extracts:

• Component type and language
• Location in the codebase
• Configuration files
• Dependencies declared in manifests

Stage 2: Ownership Analysis

The system analyzes your Git history to determine component ownership:

• Reviews commit history to identify primary contributors
• Checks for CODEOWNERS files
• Analyzes contribution patterns and frequency
• Identifies the most active maintainers

This helps you know who to contact for questions or changes.

Stage 3: Dependency Analysis

We use deterministic and Machine Learning algorithms along with our AI Agent to:

• Analyze import statements across different programming languages
• Understand semantic relationships between components
• Detect implicit dependencies that aren't declared in manifests
• Map communication patterns between services

CodeCargo understands:

ComponentA imports from ComponentB
→ Creates dependency relationship

This goes beyond simple text matching—the AI understands different programming paradigms, import styles, and language-specific patterns.

Stage 4: CI/CD Pattern Detection

The system identifies which components are actively built and deployed:

• Scans workflow files (GitHub Actions, Jenkins, etc.)
• Identifies build steps for each component
• Detects test automation
• Discovers deployment patterns (which components get deployed where)
• Tracks publish operations (npm, Docker, Maven, etc.)
• Maps deployment environments (staging, production, etc.)

Stage 5: Service Boundary Detection

Using the CI/CD analysis, the system automatically identifies service boundaries:

A component becomes a "service" when:

• It has a CI/CD pipeline that deploys it somewhere
• It represents a deployable unit (API, web app, worker, etc.)

Components that are NOT services:

• Libraries (published but not deployed)
• Shared utilities
• Test fixtures

The system assigns each service a unique identifier and groups related components together.

Stage 6: Relationship Mapping

Finally, all the data is assembled into a graph database where:

• Nodes represent repositories, components, and owners
• Edges represent relationships (dependencies, ownership, CI/CD connections)
• Metadata includes detailed information about each relationship

This graph structure allows powerful queries like:

• "Show me all services that depend on ComponentX"
• "Which components does TeamY own?"
• "What gets deployed to production?"

A link between repositories is drawn when a scan is saved, from what each component publishes and what it references: a package name, a workflow, an action, or a template. The catalog links a reference to the single component in another active repository that publishes that name.

You can scan the repositories in any order. The link appears once the second of the two has been scanned, and you do not need to scan the first one again for that link. A name that more than one component publishes is left unlinked. A reference published by a component in the same repository stays inside that repository.

Deactivating a repository removes its links to the rest of the organization. Its components remain, but they no longer publish or reference anything outside the repository.

Repository Filtering

The Service Catalog automatically filters to show only active repositories. Inactive or archived repositories are excluded from all Service Catalog views, ensuring you see only the components and services that are currently maintained and operational.

This filtering applies across all Service Catalog levels:

• Organization-wide views show only active repositories
• Project-level catalogs include only active repositories within the project
• Repository-level views are only available for active repositories

Service Catalog Detection Retry

CodeCargo automatically scans repositories to detect services and components for the Service Catalog. If a scan gets stuck or fails, you can retry the detection process:

• Stuck scans show an alert with a Retry scan button instead of an endless spinner
• Failed scans display the failure reason in tooltips and scan button titles
• Manual retry is available from the repository list actions menu (⋯ → Retry detection)
• Single repository retry can be triggered from the Service Catalog page when a scan is stuck or failed

The retry process creates a fresh scan with new credentials, ensuring that stuck scans don't interfere with new detection attempts. Scans are considered stale after 30 minutes of inactivity.

Scan Status Indicators

At the organization and project level, the Service Catalog header shows a stats strip summarizing scan status across active repositories — for example, 94 active repositories · 2 scanning · 47 scanned · 40 not scanned · 5 failed. Categories with zero repositories are omitted, and a pulsing dot appears next to the scanning count while scans are actively running.

On an individual repository page, scan status appears as a pill instead: a spinner while that repository is scanning, or Scan failed with the failure reason shown in a tooltip. An unscanned repository shows no pill, since the page body already prompts you to start a scan.

Understanding the Dashboard

The Service Graph

The graph visualization shows your architecture as an interactive diagram. Switch between Split (graph above the table), Graph, and Table with the buttons above it.

Node Types

Repository Nodes (Large containers)

• Represent Git repositories
• Contain component nodes
• Show repository name
• Display edge count badges

Component Nodes (Colored boxes)

• Represent individual components
• Show component name
• Display programming language icon and name
• Show owner avatars (up to 2 + count); hover an avatar for the owner's name

Owners are not separate nodes: they appear as avatars on each component card, and in full in the component detail panel.

Connections (Edges)

Lines between nodes show relationships:

• Dashed lines: Direct dependencies
• Arrows: Direction of dependency (A depends on B)
• Connected repositories: Indicate cross-repository dependencies

Linked Repositories

Repositories that use a shared repository sit in rows above it. Repositories with no links to others sit below.

With up to 30 linked repositories, each one is a card you expand in place. Past that, the most-used shared repositories stay cards. The rest are named tiles, or squares that show a name when you point at them: the repository, what it holds, and what it uses.

Click a tile, a square, or a card's Expand control to open that repository and what it connects to in Split, instead of expanding it on the graph. Under the filter menus, a line reads Opened from the Graph: payments-api and what it connects to, naming the repository you opened. Back to Graph or Back to Split returns you to the view you left. Opening another repository updates the line, and Back undoes each one you opened this way. Change a filter, or choose the view the line names, and the way back is cleared.

Filtering and Exploration

Component Type Filters

Control which components appear:

• Code → Services: Show only deployable services
• Code → Libraries & Tests: Show libraries, utilities, and test suites
• IaC: Show infrastructure-as-code components
• CI/CD: Show active CI/CD pipelines

Pro tip: Start with "Code → Services" to see your main services, then expand to see supporting components. Click a component card to zoom to it and open its detail panel.

Component Filter (Multi-Select)

Select specific components by name:

• Search for components in the dropdown
• Select more than one to see any of those components
• The dropdown lists only components your other filters still keep, so a new pick does not empty the view

Type, owner, repository, and search narrow together: a component is shown only when it matches every filter that is on. Several picks inside one filter match any of them. A component you already picked stays on its badge if a later filter drops it; remove the badge to clear it.

Use case: "Show me just ComponentX and ComponentY"

Owner Filter (Multi-Select)

Filter by component ownership:

• Select one or more owners
• See only components they maintain
• Understand ownership distribution

Use case: "Show me everything TeamY owns"

No owner appears when at least one component has no owner. Choose it to see those components. Combine it with other owners to see their components and the unowned ones together.

View Settings

The gear button on the graph opens Graph Settings:

• Repository Layout: Force (organic), Layered (left-to-right dependency flow), or Bands (rows grouped by component type)
• Hide Tests: Hide test components
• Show Owner Icons: Toggle owner avatars on component nodes; turn it off for a cleaner view when ownership isn't the focus

The Component Table

The table view provides a detailed, searchable list of all components:

Columns

CI/CD Indicators

Icons show which CI/CD operations are configured; hover them for a list:

• Hammer (Build): Component has automated builds
• Shield check (Test): Component has automated tests
• Rocket (Deploy): Component has automated deployment (indicates a service)
• Upload cloud (Publish): Component is published to a registry (npm, Docker Hub, etc.)

Component Descriptions and Ownership

Descriptions

Each component carries a short, plain-language description generated during repository scanning from the component's title, directory, language, type, manifests, and dependencies. The one-line version appears under the component name in the table and is included in search, so you can find a component by what it does rather than only by its name. The component detail panel shows the full description as formatted markdown.

Descriptions are regenerated only when the underlying signals change, so repeated scans of an unchanged component reuse the existing text. Org Admins can force a refresh from the Description card in the detail panel; the card shows progress while the new description is being written and updates in place when it lands.

Owners and Code Owners

Where a commit author can be matched to a member of your organization, owners render with that member's GitHub avatar, @handle, and a link to their GitHub profile — in the catalog table tooltip, on graph cards, and in the component detail panels. Matching uses the member's synced GitHub email, their commit email, and finally an exact display-name match, and only when that name is unique in the organization, so similarly named people are never linked to the wrong account.

If a repository has a CODEOWNERS file, the rules that apply to each component are captured during scanning and shown in a Code Owners card. @org/team-slug entries resolve to CodeCargo teams and @login or email entries resolve to organization members, so you see real names and teams rather than raw file entries.

Common Use Cases

1. Understanding a New Codebase

Scenario: You just joined the team and need to understand the architecture.

Steps:

1. Go to the Organization-level Service Catalog
2. Enable "Code → Services" filter only
3. Review the graph to see main services
4. Identify central services (highly connected nodes)
5. Click on services relevant to your team
6. Follow dependencies to understand service relationships

2. Planning a Refactoring

Scenario: You need to update ComponentX and want to know what will be affected.

Steps:

1. Go to the Repository or Project-level catalog
2. Click ComponentX in the graph, then View Service Details in its detail panel
3. Review the Dependents: every component that depends on ComponentX
4. Check which services ultimately depend on your changes
5. Identify owners of dependent components for coordination
6. Plan your rollout strategy based on dependency chain

3. Identifying Missing Automation

Scenario: You want to ensure all services have proper CI/CD pipelines.

Steps:

1. Apply "Code → Services" filter
2. Switch to Table view
3. Sort by CI/CD columns
4. Look for services missing Deploy indicators
5. Prioritize adding automation to high-impact services

4. Understanding Ownership Gaps

Scenario: You need to ensure adequate coverage for on-call rotations.

Steps:

1. Enable the Owner filter
2. Review components without owners (or with single owners)
3. Identify critical services with insufficient ownership
4. Review the table view for team planning

5. Architectural Review

Scenario: You're conducting a quarterly architecture review.

Steps:

1. Start at Organization level using the graph in split view
2. Present the high-level architecture
3. Identify tightly coupled clusters (many interconnected nodes)
4. Drill down to Project level for specific areas of concern
5. Review service boundaries and suggest improvements

6. Cross-Team Coordination

Scenario: Multiple teams are working on related services and need to coordinate.

Steps:

1. Use Owner filters to select both teams
2. Review shared dependencies
3. Identify services where teams interact
4. Plan integration points and communication strategies

Deep Linking and URL Sharing

The Service Catalog supports deep linking, allowing you to share specific filtered views with your team or bookmark complex filter combinations for later use.

Shareable URLs

All filter states are preserved in the URL, including:

• Component type filters (types=code-services&types=iac, or types=all)
• Specific components (components=…, repeated for each component)
• Owner filters (owners=…, repeated for each owner)
• Selected component (component=…, the one whose detail panel is open)
• Search queries (search=api)
• View mode (view=both for split, view=graph, or view=table)

Simply copy the URL from your browser to share a filtered view with colleagues.

URL Parameter Handling

The Service Catalog intelligently handles URL parameters:

• Invalid component or owner IDs fall back to the default view (code services)
• Invalid type filters show an empty state with helpful suggestions
• Missing type parameter defaults to showing code services
• Invalid view modes default to split view

Pairs Well With