# golangid/candi architecture

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

- Interactive diagram: https://gitdiagram.com/golangid/candi
- Repository: https://github.com/golangid/candi

## Overview

Candi is a Go service-framework library accompanied by a CLI that generates services, modules, handlers, and monorepo scaffolding. Its runtime workflow is to assemble registered applications, serve network protocols or consume scheduled and broker/database events, and shut them down gracefully. The graph includes the documented REST, GraphQL, gRPC, and worker capabilities, plus factories and tracing. Source excerpts are limited, so connections among unsampled protocol workers, handlers, and integrations are shown only where the tree or excerpts support them.

Main entry points: [`codebase/factory/service_factory.go`](https://github.com/golangid/candi/blob/master/codebase/factory/service_factory.go) (Service Factory), [`cmd/candi/main.go`](https://github.com/golangid/candi/blob/master/cmd/candi/main.go) (CLI Entry), [`codebase/app/graphql_server/graphql_server.go`](https://github.com/golangid/candi/blob/master/codebase/app/graphql_server/graphql_server.go) (GraphQL Server), [`codebase/app/postgres_worker/postgres_worker.go`](https://github.com/golangid/candi/blob/master/codebase/app/postgres_worker/postgres_worker.go) (Postgres Listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Project CLI"]
  node_cli_main["CLI Entry<br/>[main.go]"]
  node_generator["Project Generator"]
  node_template["Project Templates"]
  node_runner["Service Runner<br/>[service_runner.go]"]
end

subgraph group_runtime["Runtime Lifecycle"]
  node_app["Application Lifecycle<br/>[app.go]"]
  node_service_factory["Service Factory<br/>[service_factory.go]"]
  node_app_factory["Application Factory"]
  node_module_factory["Module Factory<br/>[module_factory.go]"]
end

subgraph group_delivery["Servers and Workers"]
  node_rest["REST Server<br/>[rest_server.go]"]
  node_graphql["GraphQL Server<br/>[graphql_server.go]"]
  node_grpc["gRPC Server<br/>[grpc_server.go]"]
  node_cron["Cron Worker<br/>[cron_worker.go]"]
  node_kafka["Kafka Worker<br/>[kafka_worker.go]"]
  node_rabbit["RabbitMQ Worker<br/>[rabbitmq_worker.go]"]
  node_redis["Redis Worker<br/>[redis_worker.go]"]
  node_postgres["Postgres Listener<br/>[postgres_worker.go]"]
  node_task_queue["Task Queue Worker"]
end

subgraph group_platform["Shared Platform"]
  node_middleware["Middleware<br/>[middleware.go]"]
  node_tracing["Tracing<br/>[tracer.go]"]
  node_broker["Broker Adapters<br/>[broker.go]"]
  node_handler_contracts["Handler Contracts<br/>[handlers.go]"]
end

node_developer(("Service Developer"))
node_client(("API Clients"))
node_event_source(("Event Sources"))

node_developer -->|"invokes"| node_cli_main
node_cli_main -->|"dispatches generation"| node_generator
node_generator -->|"renders templates"| node_template
node_cli_main -->|"dispatches run"| node_runner
node_developer -->|"configures service"| node_service_factory
node_app -->|"gets applications"| node_service_factory
node_service_factory -->|"registers applications"| node_app_factory
node_service_factory -->|"assembles modules"| node_module_factory
node_app -->|"serves and shuts down"| node_app_factory
node_client -->|"sends HTTP"| node_rest
node_client -->|"sends GraphQL"| node_graphql
node_client -->|"sends RPC"| node_grpc
node_event_source -->|"delivers messages"| node_kafka
node_event_source -->|"delivers messages"| node_rabbit
node_event_source -->|"publishes events"| node_redis
node_event_source -->|"emits changes"| node_postgres
node_event_source -->|"triggers schedule"| node_cron
node_event_source -->|"queues tasks"| node_task_queue
node_graphql -->|"collects resolvers"| node_module_factory
node_postgres -->|"dispatches handlers"| node_handler_contracts
node_rest -->|"applies middleware"| node_middleware
node_graphql -->|"traces requests"| node_tracing
node_postgres -->|"traces events"| node_tracing
node_kafka -.->|"uses adapter"| node_broker
node_rabbit -.->|"uses adapter"| node_broker
node_redis -.->|"uses adapter"| node_broker

click node_cli_main "https://github.com/golangid/candi/blob/master/cmd/candi/main.go"
click node_generator "https://github.com/golangid/candi/blob/master/cmd/candi/project_generator.go"
click node_template "https://github.com/golangid/candi/blob/master/cmd/candi/template_service.go"
click node_runner "https://github.com/golangid/candi/blob/master/cmd/candi/service_runner.go"
click node_app "https://github.com/golangid/candi/blob/master/codebase/app/app.go"
click node_service_factory "https://github.com/golangid/candi/blob/master/codebase/factory/service_factory.go"
click node_app_factory "https://github.com/golangid/candi/blob/master/codebase/factory/app_server_factory.go"
click node_module_factory "https://github.com/golangid/candi/blob/master/codebase/factory/module_factory.go"
click node_rest "https://github.com/golangid/candi/blob/master/codebase/app/rest_server/rest_server.go"
click node_graphql "https://github.com/golangid/candi/blob/master/codebase/app/graphql_server/graphql_server.go"
click node_grpc "https://github.com/golangid/candi/blob/master/codebase/app/grpc_server/grpc_server.go"
click node_cron "https://github.com/golangid/candi/blob/master/codebase/app/cron_worker/cron_worker.go"
click node_kafka "https://github.com/golangid/candi/blob/master/codebase/app/kafka_worker/kafka_worker.go"
click node_rabbit "https://github.com/golangid/candi/blob/master/codebase/app/rabbitmq_worker/rabbitmq_worker.go"
click node_redis "https://github.com/golangid/candi/blob/master/codebase/app/redis_worker/redis_worker.go"
click node_postgres "https://github.com/golangid/candi/blob/master/codebase/app/postgres_worker/postgres_worker.go"
click node_task_queue "https://github.com/golangid/candi/blob/master/codebase/app/task_queue_worker/task_queue_worker.go"
click node_middleware "https://github.com/golangid/candi/blob/master/middleware/middleware.go"
click node_tracing "https://github.com/golangid/candi/blob/master/tracer/tracer.go"
click node_broker "https://github.com/golangid/candi/blob/master/broker/broker.go"
click node_handler_contracts "https://github.com/golangid/candi/blob/master/codebase/interfaces/handlers.go"

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_cli_main,node_generator,node_template,node_runner,node_client toneBlue
class node_app,node_service_factory,node_app_factory,node_module_factory toneAmber
class node_rest,node_graphql,node_grpc,node_cron,node_kafka,node_rabbit,node_redis,node_postgres,node_task_queue toneMint
class node_middleware,node_tracing,node_broker,node_handler_contracts toneRose
class node_developer,node_event_source toneIndigo
```

## Components

### Project CLI

- [CLI Entry](https://github.com/golangid/candi/blob/master/cmd/candi/main.go): `cmd/candi/main.go`
- [Project Generator](https://github.com/golangid/candi/blob/master/cmd/candi/project_generator.go): `cmd/candi/project_generator.go`
- [Project Templates](https://github.com/golangid/candi/blob/master/cmd/candi/template_service.go): `cmd/candi/template_service.go`
- [Service Runner](https://github.com/golangid/candi/blob/master/cmd/candi/service_runner.go): `cmd/candi/service_runner.go`

### Runtime Lifecycle

- [Application Lifecycle](https://github.com/golangid/candi/blob/master/codebase/app/app.go): `codebase/app/app.go`
- [Service Factory](https://github.com/golangid/candi/blob/master/codebase/factory/service_factory.go): `codebase/factory/service_factory.go`
- [Application Factory](https://github.com/golangid/candi/blob/master/codebase/factory/app_server_factory.go): `codebase/factory/app_server_factory.go`
- [Module Factory](https://github.com/golangid/candi/blob/master/codebase/factory/module_factory.go): `codebase/factory/module_factory.go`

### Servers and Workers

- [REST Server](https://github.com/golangid/candi/blob/master/codebase/app/rest_server/rest_server.go): `codebase/app/rest_server/rest_server.go`
- [GraphQL Server](https://github.com/golangid/candi/blob/master/codebase/app/graphql_server/graphql_server.go): `codebase/app/graphql_server/graphql_server.go`
- [gRPC Server](https://github.com/golangid/candi/blob/master/codebase/app/grpc_server/grpc_server.go): `codebase/app/grpc_server/grpc_server.go`
- [Cron Worker](https://github.com/golangid/candi/blob/master/codebase/app/cron_worker/cron_worker.go): `codebase/app/cron_worker/cron_worker.go`
- [Kafka Worker](https://github.com/golangid/candi/blob/master/codebase/app/kafka_worker/kafka_worker.go): `codebase/app/kafka_worker/kafka_worker.go`
- [RabbitMQ Worker](https://github.com/golangid/candi/blob/master/codebase/app/rabbitmq_worker/rabbitmq_worker.go): `codebase/app/rabbitmq_worker/rabbitmq_worker.go`
- [Redis Worker](https://github.com/golangid/candi/blob/master/codebase/app/redis_worker/redis_worker.go): `codebase/app/redis_worker/redis_worker.go`
- [Postgres Listener](https://github.com/golangid/candi/blob/master/codebase/app/postgres_worker/postgres_worker.go): `codebase/app/postgres_worker/postgres_worker.go`
- [Task Queue Worker](https://github.com/golangid/candi/blob/master/codebase/app/task_queue_worker/task_queue_worker.go): `codebase/app/task_queue_worker/task_queue_worker.go`

### Shared Platform

- [Middleware](https://github.com/golangid/candi/blob/master/middleware/middleware.go): `middleware/middleware.go`
- [Tracing](https://github.com/golangid/candi/blob/master/tracer/tracer.go): `tracer/tracer.go`
- [Broker Adapters](https://github.com/golangid/candi/blob/master/broker/broker.go): `broker/broker.go`
- [Handler Contracts](https://github.com/golangid/candi/blob/master/codebase/interfaces/handlers.go): `codebase/interfaces/handlers.go`

### Other components

- **Service Developer**
- **API Clients**
- **Event Sources**

## Connections

- Service Developer → CLI Entry: invokes
- CLI Entry → Project Generator: dispatches generation
- Project Generator → Project Templates: renders templates
- CLI Entry → Service Runner: dispatches run
- Service Developer → Service Factory: configures service
- Application Lifecycle → Service Factory: gets applications
- Service Factory → Application Factory: registers applications
- Service Factory → Module Factory: assembles modules
- Application Lifecycle → Application Factory: serves and shuts down
- API Clients → REST Server: sends HTTP
- API Clients → GraphQL Server: sends GraphQL
- API Clients → gRPC Server: sends RPC
- Event Sources → Kafka Worker: delivers messages
- Event Sources → RabbitMQ Worker: delivers messages
- Event Sources → Redis Worker: publishes events
- Event Sources → Postgres Listener: emits changes
- Event Sources → Cron Worker: triggers schedule
- Event Sources → Task Queue Worker: queues tasks
- GraphQL Server → Module Factory: collects resolvers
- Postgres Listener → Handler Contracts: dispatches handlers
- REST Server → Middleware: applies middleware
- GraphQL Server → Tracing: traces requests
- Postgres Listener → Tracing: traces events
- Kafka Worker → Broker Adapters: uses adapter
- RabbitMQ Worker → Broker Adapters: uses adapter
- Redis Worker → Broker Adapters: uses adapter