How tejamahesh1433/portforge works
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: api Resource APIs · repositories Repositories · config_manager.py Project Config Apply · cli.py Agent CLI
Components 31
Host Agent
- Agent CLI
agent/portforge_agent/cli.py - Host Identity
agent/portforge_agent/identity.py - Port Discovery
agent/portforge_agent/discovery.py - Platform Collectors
agent/portforge_agent/collectors - Agent Sync
agent/portforge_agent/central_sync.py - Central Client
agent/portforge_agent/central_client.py - Project Config Apply
agent/portforge_agent/config_manager.py
Central Registry
- Central API
backend/app/main.py - Agent Endpoints
backend/app/api/agents.py - Enrollment Service
backend/app/services/enrollment_service.py - Snapshot Ingestion
backend/app/services/ingestion_service.py - Resource APIs
backend/app/api - Domain Services
backend/app/services - Repositories
backend/app/repositories - Fleet Database
backend/app/database.py
Dashboard
- Dashboard Pages
dashboard/app - Data Hooks
dashboard/hooks - Dashboard API Client
dashboard/lib/api - Admin Proxies
dashboard/app/api
Port Workflows
- Port And Fleet Views
dashboard/app - Reservations
backend/app/services/reservation_service.py - Allocations
backend/app/services/allocation_service.py - Recommendations
backend/app/services/recommendation_service.py - Conflict Detection
backend/app/services/conflict_service.py
Fleet Operations
- Host Lifecycle
backend/app/services/host_lifecycle_service.py - Agent Upgrades
backend/app/services/upgrade_service.py - Activity History
backend/app/models/activity.py
Other components
- Operator
- Managed Host
- Docker / Compose
- Kubernetes
Connections 34
- 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