# tejamahesh1433/portforge architecture

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

- Interactive diagram: https://gitdiagram.com/tejamahesh1433/portforge
- Repository: https://github.com/tejamahesh1433/portforge

## Overview

PortForge coordinates port discovery and allocation across developer and deployment hosts. A host agent collects process and Docker/Compose port observations, then synchronizes snapshots to the Central API, which maintains fleet state and handles reservations and allocations in PostgreSQL. Operators use the dashboard to inspect fleet health, ports, conflicts, projects, recommendations, and activity, and to manage hosts and upgrades. The agent also supports local project configuration planning and application. Relationships follow the README and sampled route, enrollment, ingestion, and dashboard proxy code; unsampled subsystem wiring is shown only where documented.

Main entry points: [`backend/app/api`](https://github.com/tejamahesh1433/portforge/tree/main/backend/app/api) (Resource APIs), [`backend/app/repositories`](https://github.com/tejamahesh1433/portforge/tree/main/backend/app/repositories) (Repositories), [`agent/portforge_agent/config_manager.py`](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/config_manager.py) (Project Config Apply), [`agent/portforge_agent/cli.py`](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/cli.py) (Agent CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host Agent"]
  node_agent_cli["Agent CLI<br/>[cli.py]"]
  node_agent_identity["Host Identity<br/>[identity.py]"]
  node_discovery["Port Discovery<br/>[discovery.py]"]
  node_collectors["Platform Collectors"]
  node_agent_sync["Agent Sync<br/>[central_sync.py]"]
  node_agent_client["Central Client<br/>[central_client.py]"]
  node_config_manager["Project Config Apply<br/>[config_manager.py]"]
end

subgraph group_central["Central Registry"]
  node_central_app["Central API<br/>[main.py]"]
  node_agent_routes["Agent Endpoints<br/>[agents.py]"]
  node_enrollment["Enrollment Service"]
  node_ingestion["Snapshot Ingestion"]
  node_api_routes["Resource APIs"]
  node_domain_services["Domain Services"]
  node_repositories["Repositories"]
  node_postgres[("Fleet Database<br/>[database.py]")]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard Pages"]
  node_dashboard_hooks["Data Hooks"]
  node_dashboard_api["Dashboard API Client"]
  node_admin_proxies["Admin Proxies"]
end

subgraph group_port_workflows["Port Workflows"]
  node_port_views["Port And Fleet Views"]
  node_reservations["Reservations"]
  node_allocations["Allocations"]
  node_recommendations["Recommendations"]
  node_conflicts["Conflict Detection"]
end

subgraph group_host_ops["Fleet Operations"]
  node_lifecycle["Host Lifecycle"]
  node_upgrades["Agent Upgrades<br/>[upgrade_service.py]"]
  node_activity["Activity History<br/>[activity.py]"]
end

node_operator(("Operator"))
node_host(("Managed Host"))
node_docker["Docker / Compose"]
node_kubernetes["Kubernetes"]

node_operator -->|"runs commands"| node_agent_cli
node_agent_cli -->|"loads identity"| node_agent_identity
node_agent_cli -->|"requests scan"| node_discovery
node_host -->|"supplies host state"| node_collectors
node_collectors -->|"collect observations"| node_discovery
node_docker -.->|"container bindings"| node_collectors
node_discovery -->|"sends snapshot"| node_agent_sync
node_agent_sync -->|"uses API client"| node_agent_client
node_agent_client -->|"enrolls and syncs"| node_agent_routes
node_agent_routes -->|"enrolls host"| node_enrollment
node_agent_routes -->|"submits observations"| node_ingestion
node_enrollment -->|"stores host credentials"| node_repositories
node_ingestion -->|"records snapshot"| node_repositories
node_api_routes -->|"dispatches requests"| node_domain_services
node_domain_services -->|"reads and writes"| node_repositories
node_repositories -->|"persists state"| node_postgres
node_central_app -->|"mounts routers"| node_api_routes
node_operator -->|"views and manages"| node_dashboard_ui
node_dashboard_ui -->|"requests data"| node_dashboard_hooks
node_dashboard_hooks -->|"fetches resources"| node_dashboard_api
node_dashboard_api -->|"calls Central"| node_api_routes
node_dashboard_ui -->|"requests admin actions"| node_admin_proxies
node_admin_proxies -->|"forwards authorized calls"| node_api_routes
node_api_routes -->|"serves port and fleet data"| node_port_views
node_api_routes -->|"handles reservation requests"| node_reservations
node_api_routes -->|"handles allocation requests"| node_allocations
node_api_routes -->|"serves suggestions"| node_recommendations
node_api_routes -->|"serves conflicts"| node_conflicts
node_api_routes -->|"manages host state"| node_lifecycle
node_api_routes -->|"manages upgrades"| node_upgrades
node_ingestion -->|"records port events"| node_activity
node_config_manager -->|"checks allocations"| node_agent_client
node_config_manager -.->|"edits Compose config"| node_docker
node_config_manager -.->|"edits manifests"| node_kubernetes

click node_agent_cli "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/cli.py"
click node_agent_identity "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/identity.py"
click node_discovery "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/discovery.py"
click node_collectors "https://github.com/tejamahesh1433/portforge/tree/main/agent/portforge_agent/collectors"
click node_agent_sync "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/central_sync.py"
click node_agent_client "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/central_client.py"
click node_config_manager "https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/config_manager.py"
click node_central_app "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/main.py"
click node_agent_routes "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/api/agents.py"
click node_enrollment "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/enrollment_service.py"
click node_ingestion "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/ingestion_service.py"
click node_api_routes "https://github.com/tejamahesh1433/portforge/tree/main/backend/app/api"
click node_domain_services "https://github.com/tejamahesh1433/portforge/tree/main/backend/app/services"
click node_repositories "https://github.com/tejamahesh1433/portforge/tree/main/backend/app/repositories"
click node_postgres "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/database.py"
click node_dashboard_ui "https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app"
click node_dashboard_hooks "https://github.com/tejamahesh1433/portforge/tree/main/dashboard/hooks"
click node_dashboard_api "https://github.com/tejamahesh1433/portforge/tree/main/dashboard/lib/api"
click node_admin_proxies "https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app/api"
click node_port_views "https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app"
click node_reservations "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/reservation_service.py"
click node_allocations "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/allocation_service.py"
click node_recommendations "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/recommendation_service.py"
click node_conflicts "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/conflict_service.py"
click node_lifecycle "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/host_lifecycle_service.py"
click node_upgrades "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/upgrade_service.py"
click node_activity "https://github.com/tejamahesh1433/portforge/blob/main/backend/app/models/activity.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_agent_cli,node_agent_identity,node_discovery,node_collectors,node_agent_sync,node_agent_client,node_config_manager toneBlue
class node_central_app,node_agent_routes,node_enrollment,node_ingestion,node_api_routes,node_domain_services,node_repositories,node_postgres toneAmber
class node_dashboard_ui,node_dashboard_hooks,node_dashboard_api,node_admin_proxies toneMint
class node_port_views,node_reservations,node_allocations,node_recommendations,node_conflicts toneRose
class node_lifecycle,node_upgrades,node_activity,node_operator,node_host,node_docker,node_kubernetes toneIndigo
```

## Components

### Host Agent

- [Agent CLI](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/cli.py): `agent/portforge_agent/cli.py`
- [Host Identity](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/identity.py): `agent/portforge_agent/identity.py`
- [Port Discovery](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/discovery.py): `agent/portforge_agent/discovery.py`
- [Platform Collectors](https://github.com/tejamahesh1433/portforge/tree/main/agent/portforge_agent/collectors): `agent/portforge_agent/collectors`
- [Agent Sync](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/central_sync.py): `agent/portforge_agent/central_sync.py`
- [Central Client](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/central_client.py): `agent/portforge_agent/central_client.py`
- [Project Config Apply](https://github.com/tejamahesh1433/portforge/blob/main/agent/portforge_agent/config_manager.py): `agent/portforge_agent/config_manager.py`

### Central Registry

- [Central API](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Agent Endpoints](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/api/agents.py): `backend/app/api/agents.py`
- [Enrollment Service](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/enrollment_service.py): `backend/app/services/enrollment_service.py`
- [Snapshot Ingestion](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Resource APIs](https://github.com/tejamahesh1433/portforge/tree/main/backend/app/api): `backend/app/api`
- [Domain Services](https://github.com/tejamahesh1433/portforge/tree/main/backend/app/services): `backend/app/services`
- [Repositories](https://github.com/tejamahesh1433/portforge/tree/main/backend/app/repositories): `backend/app/repositories`
- [Fleet Database](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/database.py): `backend/app/database.py`

### Dashboard

- [Dashboard Pages](https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app): `dashboard/app`
- [Data Hooks](https://github.com/tejamahesh1433/portforge/tree/main/dashboard/hooks): `dashboard/hooks`
- [Dashboard API Client](https://github.com/tejamahesh1433/portforge/tree/main/dashboard/lib/api): `dashboard/lib/api`
- [Admin Proxies](https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app/api): `dashboard/app/api`

### Port Workflows

- [Port And Fleet Views](https://github.com/tejamahesh1433/portforge/tree/main/dashboard/app): `dashboard/app`
- [Reservations](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/reservation_service.py): `backend/app/services/reservation_service.py`
- [Allocations](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/allocation_service.py): `backend/app/services/allocation_service.py`
- [Recommendations](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/recommendation_service.py): `backend/app/services/recommendation_service.py`
- [Conflict Detection](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/conflict_service.py): `backend/app/services/conflict_service.py`

### Fleet Operations

- [Host Lifecycle](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/host_lifecycle_service.py): `backend/app/services/host_lifecycle_service.py`
- [Agent Upgrades](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/services/upgrade_service.py): `backend/app/services/upgrade_service.py`
- [Activity History](https://github.com/tejamahesh1433/portforge/blob/main/backend/app/models/activity.py): `backend/app/models/activity.py`

### Other components

- **Operator**
- **Managed Host**
- **Docker / Compose**
- **Kubernetes**

## Connections

- Operator → Agent CLI: runs commands
- Agent CLI → Host Identity: loads identity
- Agent CLI → Port Discovery: requests scan
- Managed Host → Platform Collectors: supplies host state
- Platform Collectors → Port Discovery: collect observations
- Docker / Compose → Platform Collectors: container bindings
- Port Discovery → Agent Sync: sends snapshot
- Agent Sync → Central Client: uses API client
- Central Client → Agent Endpoints: enrolls and syncs
- Agent Endpoints → Enrollment Service: enrolls host
- Agent Endpoints → Snapshot Ingestion: submits observations
- Enrollment Service → Repositories: stores host credentials
- Snapshot Ingestion → Repositories: records snapshot
- Resource APIs → Domain Services: dispatches requests
- Domain Services → Repositories: reads and writes
- Repositories → Fleet Database: persists state
- Central API → Resource APIs: mounts routers
- Operator → Dashboard Pages: views and manages
- Dashboard Pages → Data Hooks: requests data
- Data Hooks → Dashboard API Client: fetches resources
- Dashboard API Client → Resource APIs: calls Central
- Dashboard Pages → Admin Proxies: requests admin actions
- Admin Proxies → Resource APIs: forwards authorized calls
- Resource APIs → Port And Fleet Views: serves port and fleet data
- Resource APIs → Reservations: handles reservation requests
- Resource APIs → Allocations: handles allocation requests
- Resource APIs → Recommendations: serves suggestions
- Resource APIs → Conflict Detection: serves conflicts
- Resource APIs → Host Lifecycle: manages host state
- Resource APIs → Agent Upgrades: manages upgrades
- Snapshot Ingestion → Activity History: records port events
- Project Config Apply → Central Client: checks allocations
- Project Config Apply → Docker / Compose: edits Compose config
- Project Config Apply → Kubernetes: edits manifests