# crocofied/corecontrol architecture

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

- Interactive diagram: https://gitdiagram.com/crocofied/corecontrol
- Repository: https://github.com/crocofied/corecontrol

## Overview

##### Project Type & Purpose
- CoreControl is a self-hosted, full-stack server-infrastructure management dashboard.
- It consists of a Next.js + TypeScript monolith for UI and API, a Go-based agent for background monitoring, and a PostgreSQL database.

##### High-Level File Structure Analysis
- Top-level “app” directory: Next.js app routes, pages, and UI components.
- “agent” directory: Go service with its own Dockerfile, modules, internal packages (server, database, models, notifications, monitoring).
- “prisma” and “lib/generated/prisma”: database schema, migrations, and generated client.
- Configuration/deployment: Dockerfile, docker-compose (compose.yml), Next.js (next.config.ts), TypeScript, PostCSS, VitePress docs.

##### README Insights
- Describes three runtime services: web (Next.js), agent (Go), db (Postgres).
- Shows Docker-Compose setup with environment variables, health checks, volumes.
- Highlights tech stack: Next.js, Go, Prisma, Tailwind/shadcn, React Flow, Glances, external notification channels.

##### Main Components & Their Interactions
a. Frontend (Next.js UI)
- Components: pages (login, dashboard, servers, applications, networks, uptime, settings), shared UI library (components/ui), theme provider.
- Serves HTML/CSS/JS to browser.
b. Backend API (Next.js serverless routes)
- Under app/api/*: CRUD endpoints for auth, servers, applications, notifications, flowchart, dashboard, settings, uptime.
- Business logic uses Prisma client (lib/prisma.ts) to query PostgreSQL.
c. Database (PostgreSQL + Prisma)
- Schema defined in prisma/schema.prisma, migrations under prisma/migrations.
- Persistent storage for users, servers, applications, notifications, uptime logs, settings.
d. Agent (Go microservice)
- Periodically polls servers via Glances (monitor.go), writes metrics to database, and triggers notifications via internal/notifications.
- Exposes minimal HTTP interface (internal/server) for potential remote control or health checks.
e. External Services
- Glances: system-monitoring tool invoked by the agent.
- Notification providers: Email, Discord, Echobell, Gotify, Ntfy, Pushover, Telegram via agent.

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI layer, API layer, monitoring agent, data persistence, and external integrations are distinct.
- Monorepo + Polyglot Microservices: Next.js and Go live side-by-side, communicate via shared database.
- Serverless API Routes: Next.js routes act as lightweight functions, no separate backend server code.
- Event-Driven Monitoring: Agent writes metrics and events to DB; API reads and aggregates uptime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Browser/Client"]:::client

    %% Web Service Layer
    subgraph "Web Service (Next.js)" 
        direction TB
        NextUI["Next.js UI<br/>(app/layout.tsx, pages/*)"]:::frontend
        SharedUI["Shared UI Components<br/>(components/ui, app-sidebar.tsx, theme-provider.tsx, status-indicator.tsx)"]:::frontend
        API["Next.js Serverless API<br/>(app/api/*)"]:::backend
        PrismaHelper["Prisma Helper<br/>(lib/prisma.ts)"]:::backend
        Utils["Utility Functions<br/>(lib/utils.ts)"]:::backend
    end

    %% Agent Service
    subgraph "Agent Service (Go)" 
        direction TB
        AgentCLI["Agent CLI Entry Point<br/>(agent/cmd/agent/main.go)"]:::agent
        AgentServer["Agent HTTP Server<br/>(agent/internal/server/monitor.go)"]:::agent
        MonitorLogic["Monitoring Logic<br/>(agent/internal/app/monitor.go)"]:::agent
        DBIntegration["DB Integration<br/>(agent/internal/database/database.go)"]:::agent
        Models["Data Models<br/>(agent/internal/models/models.go)"]:::agent
        Notifications["Notifications Module<br/>(agent/internal/notifications/notifications.go)"]:::agent
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        Postgres["PostgreSQL DB"]:::db
        PrismaSchema["Prisma Schema & Migrations<br/>(prisma/schema.prisma, prisma/migrations)"]:::db
        PrismaClient["Prisma Client<br/>(lib/generated/prisma, prisma/client)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Glances["Glances (System Metrics)"]:::external
        NotifProviders["Notification Providers<br/>(Email, Discord, Pushover, etc.)"]:::external
    end

    %% Connections
    Browser -->|"HTTP" | NextUI
    NextUI -->|"calls API routes"| API
    API -->|"uses helper"| PrismaHelper
    API -->|"uses utils"| Utils
    PrismaHelper -->|"queries"| PrismaClient
    PrismaClient -->|"SQL queries"| Postgres
    API -->|"direct ORM"| Postgres

    AgentCLI -->|"spawns"| AgentServer
    AgentCLI -->|"runs"| MonitorLogic
    MonitorLogic -->|"polls"| Glances
    MonitorLogic -->|"writes metrics"| Postgres
    MonitorLogic -->|"saves via"| DBIntegration
    DBIntegration -->|"uses models"| Models
    MonitorLogic -->|"triggers"| Notifications
    Notifications -->|"contacts"| NotifProviders
    AgentServer -->|"health checks"| Browser

    %% Click Events
    click NextUI "https://github.com/crocofied/corecontrol/tree/main/app/dashboard"
    click SharedUI "https://github.com/crocofied/corecontrol/tree/main/components/ui"
    click API "https://github.com/crocofied/corecontrol/tree/main/app/api"
    click PrismaHelper "https://github.com/crocofied/corecontrol/blob/main/lib/prisma.ts"
    click Utils "https://github.com/crocofied/corecontrol/blob/main/lib/utils.ts"
    click PrismaSchema "https://github.com/crocofied/corecontrol/blob/main/prisma/schema.prisma"
    click PrismaClient "https://github.com/crocofied/corecontrol/tree/main/lib/generated/prisma"
    click AgentCLI "https://github.com/crocofied/corecontrol/blob/main/agent/cmd/agent/main.go"
    click AgentServer "https://github.com/crocofied/corecontrol/blob/main/agent/internal/server/monitor.go"
    click MonitorLogic "https://github.com/crocofied/corecontrol/blob/main/agent/internal/app/monitor.go"
    click DBIntegration "https://github.com/crocofied/corecontrol/blob/main/agent/internal/database/database.go"
    click Models "https://github.com/crocofied/corecontrol/blob/main/agent/internal/models/models.go"
    click Notifications "https://github.com/crocofied/corecontrol/blob/main/agent/internal/notifications/notifications.go"
    click Dockerfile "https://github.com/crocofied/corecontrol/tree/main/Dockerfile"
    click NextConfig "https://github.com/crocofied/corecontrol/blob/main/next.config.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef frontend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef backend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef agent fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef db fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
