Skip to content
This repository was archived by the owner on Aug 29, 2026. It is now read-only.

Commit 8e389c9

Browse files
ovvesleyovvesley
committed
chore: remove documentation files and assets for AkôFlow
1 parent 92347b7 commit 8e389c9

24 files changed

Lines changed: 514 additions & 508 deletions

‎.github/ai/AGENTS.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Akoflow Agent Guide
2+
3+
This repository uses this file as the shared architecture reference for AI agents.
4+
5+
## Core Shape
6+
7+
- Go project with two binaries: client and server.
8+
- The server is layered: HTTP handlers, services, runtimes, connectors, repositories and entities.
9+
- `config.App()` is the dependency composition root.
10+
11+
## Primary Flows
12+
13+
- Client submits a workflow to the server.
14+
- Server persists workflow and activities.
15+
- Orchestrator schedules pending work.
16+
- Worker dispatches activity execution.
17+
- Runtime wrapper delegates to runtime service.
18+
- Runtime service uses connectors and repositories to execute and monitor the job.
19+
20+
## Runtime Order For Debugging
21+
22+
1. `pkg/server/services/run_activity_in_cluster_service`
23+
2. `pkg/server/runtimes/runtime.go`
24+
3. `pkg/server/runtimes/<runtime>` wrapper
25+
4. `pkg/server/runtimes/<runtime>/<runtime>_service`
26+
5. connector package
27+
6. repository layer
28+
29+
## Important Invariants
30+
31+
- Handlers should not talk directly to repositories.
32+
- Runtime wrappers should stay thin.
33+
- Runtime services contain the real execution logic.
34+
- File persistence depends on the correct mount path inside the runtime.
35+
- Singularity and HPC are the most sensitive to mount-path mismatches.
36+
37+
## Key References
38+
39+
- `AI_ARCHITECTURE.md`
40+
- `AI_RUNTIME_EXECUTION_FLOW.md`

‎.github/ai/AI_ARCHITECTURE.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Akoflow AI Architecture Map
2+
3+
Purpose: machine-readable notes for AI agents working on this repository.
4+
5+
## System Shape
6+
7+
- Akoflow is the workflow engine core of the system.
8+
- Its job is to coordinate workflow execution across supported infrastructures.
9+
- Supported execution targets are Kubernetes clusters and HPC environments managed with Slurm.
10+
- Language: Go.
11+
- Main split: client binary and server binary.
12+
- Core pattern: layered architecture with config, handlers, services, runtimes, connectors, repositories and entities.
13+
14+
## Entry Points
15+
16+
- `cmd/client/main.go`: selects the CLI command and runs the client service.
17+
- `cmd/server/main.go`: bootstraps config and starts healthcheck, worker, orchestrator, monitor, garbage collector and HTTP server.
18+
19+
## High-Level Flow
20+
21+
1. Client reads a workflow file and submits it to the server.
22+
2. HTTP handlers receive the request and call application services.
23+
3. Services persist workflow and activity state through repositories.
24+
4. The orchestrator loads pending workflows and schedules activities.
25+
5. The worker consumes activity IDs and dispatches them to the selected runtime.
26+
6. The runtime wrapper delegates to the runtime service.
27+
7. The runtime service uses connectors and repositories to execute, monitor and finalize the job.
28+
29+
## Layer Responsibilities
30+
31+
### Config
32+
33+
- `pkg/server/config/app_container.go` wires repositories, connectors, logger, helpers and renderer.
34+
- `config.App()` is the global dependency source.
35+
36+
### HTTP
37+
38+
- `pkg/server/engine/httpserver` exposes the HTTP server.
39+
- `pkg/server/engine/httpserver/handlers` contains the route handlers.
40+
- Handlers should only coordinate input/output and call services.
41+
42+
### Services
43+
44+
- `pkg/server/services` contains business logic.
45+
- This layer orchestrates workflow creation, scheduling, monitoring, metrics, logs and runtime execution.
46+
47+
### Repositories
48+
49+
- `pkg/server/database/repository` persists workflow, activity, runtime, schedule, storage, logs and metrics data.
50+
- SQLite is the default persistence backend.
51+
52+
### Entities
53+
54+
- `pkg/server/entities` holds the domain models.
55+
- Workflow and activity entities are the main data carriers across layers.
56+
57+
### Runtimes
58+
59+
- `pkg/server/runtimes/runtime.go` defines the common runtime interface and the runtime factory.
60+
- Supported runtime names: `local`, `singularity`, `k8s`, `hpc`, `docker`.
61+
62+
### Connectors
63+
64+
- `pkg/server/connector` contains adapters for local shell execution, Singularity, Kubernetes and HPC integration.
65+
66+
## Composition Model
67+
68+
- Runtime wrappers are thin adapters.
69+
- Runtime services contain the real execution logic.
70+
- Runtime services depend on repositories for state and connectors for external execution.
71+
- Entities flow through the system as the shared domain model.
72+
73+
## Relationship Rules
74+
75+
- Handlers call services, not repositories.
76+
- Services may call repositories and connectors.
77+
- Runtimes are selected from workflow/activity metadata.
78+
- Runtime wrappers should not contain business logic.
79+
- Connectors should isolate external APIs and shell commands.
80+
81+
## Important Paths
82+
83+
- Client entry: `cmd/client/main.go`
84+
- Server entry: `cmd/server/main.go`
85+
- App container: `pkg/server/config/app_container.go`
86+
- Runtime factory: `pkg/server/runtimes/runtime.go`
87+
- Activity dispatch: `pkg/server/services/run_activity_in_cluster_service`
88+
89+
## Persistence Note
90+
91+
- File persistence depends on the runtime mount path being consistent between host and execution environment.
92+
- This is critical for Singularity and HPC, where generated artifacts must remain visible after job completion.
93+
94+
## What AI Should Infer
95+
96+
- The project is an execution engine, not just an API service.
97+
- The server translates workflow definitions into jobs for the target runtime environment.
98+
- The codebase is not monolithic; it is a composition of small services.
99+
- Runtime behavior is delegated, not centralized.
100+
- The app container is the main dependency graph.
101+
- Most bugs around execution come from mount paths, runtime selection, or repository state transitions.

‎.github/ai/AI_RUNTIME_EXECUTION_FLOW.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Akoflow Runtime Execution Flow for AI
2+
3+
Purpose: compact reference for how each runtime works and how the classes relate.
4+
5+
Akoflow is the workflow engine core of the project. It takes workflow definitions and turns them into executions on supported backends.
6+
7+
Supported backends:
8+
9+
- Kubernetes clusters
10+
- HPC environments orchestrated with Slurm
11+
12+
## Shared Dispatch Path
13+
14+
`RunActivityInClusterService` is the common entrypoint for activity execution.
15+
16+
This service is part of the execution core: it decides where the activity runs and forwards control to the correct runtime implementation.
17+
18+
1. Load `WorkflowActivities` and `Workflow` from repositories.
19+
2. Read `runtimeId` from the activity.
20+
3. Call `runtimes.GetRuntimeInstance(runtimeId)`.
21+
4. Execute `ApplyJob(workflowID, activityID)` on the selected runtime wrapper.
22+
23+
## Runtime Pattern
24+
25+
- Wrapper package: `pkg/server/runtimes/<runtime>`.
26+
- Service package: `pkg/server/runtimes/<runtime>/<runtime>_service`.
27+
- Wrapper: implements the common interface and delegates.
28+
- Service: builds commands, calls connectors, updates repositories, collects logs and metrics.
29+
30+
## Local Runtime
31+
32+
### Main classes
33+
34+
- `LocalRuntime`
35+
- `LocalRuntimeService`
36+
- `connector_local`
37+
38+
### Execution
39+
40+
1. `LocalRuntime.ApplyJob` delegates to `LocalRuntimeService.ApplyJob`.
41+
2. The service loads activity and workflow records.
42+
3. It builds a local shell command from `wfa.Run`.
43+
4. It appends a completion marker file and redirects stdout/stderr to the mount path.
44+
5. `connector_local.RunCommand` executes the command.
45+
6. Workflow and activity status are set to running.
46+
7. The process ID is saved in the activity record.
47+
48+
### Verification
49+
50+
- `VerifyActivitiesWasFinished` checks for the completion marker file.
51+
- If the job is still running, it extracts metrics and logs from the command output.
52+
- Metrics go to `metrics_repository` and logs go to `logs_repository`.
53+
54+
## Singularity Runtime
55+
56+
### Main classes
57+
58+
- `SingularityRuntime`
59+
- `SingularityRuntimeService`
60+
- `MakeSingularityActivityService`
61+
- `connector_singularity`
62+
63+
### Execution
64+
65+
1. `SingularityRuntime.ApplyJob` delegates to `SingularityRuntimeService.ApplyJob`.
66+
2. The service loads activity and workflow records.
67+
3. `MakeSingularityActivityService` creates the `singularity exec` command.
68+
4. The command binds the workflow mount path and sets the container working directory.
69+
5. `connector_singularity.RunCommand` submits the command.
70+
6. Workflow and activity status are updated.
71+
7. The process ID is saved.
72+
73+
### Verification
74+
75+
- `VerifyActivitiesWasFinished` runs the Singularity monitor script.
76+
- The output is parsed to detect completion.
77+
- Metrics and logs are extracted and persisted when the job is still active.
78+
79+
## HPC Runtime
80+
81+
### Main classes
82+
83+
- `HpcRuntime`
84+
- `HPCRuntimeService`
85+
- `MakeSingularityActivityService`
86+
- `MakeSBatchHPCRuntimeActivityService`
87+
- `connector_hpc`
88+
- `runtime_repository`
89+
90+
### See Also
91+
92+
- [`HPC_EXECUTION.md`](HPC_EXECUTION.md) contains the full AI-focused HPC execution map.
93+
94+
### Execution
95+
96+
1. `HpcRuntime.ApplyJob` delegates to `HPCRuntimeService.ApplyJob`.
97+
2. The service loads activity and workflow records.
98+
3. It may prepare workflow data and environment for the first activity.
99+
4. Runtime metadata is loaded from `runtime_repository`.
100+
5. `MakeSingularityActivityService` builds the Singularity command used on the cluster.
101+
6. `MakeSBatchHPCRuntimeActivityService` wraps that command in an sbatch submission.
102+
7. `connector_hpc` checks VPN connectivity.
103+
8. `connector_hpc` submits the remote command.
104+
9. The returned job ID is stored as the process ID.
105+
10. Workflow and activity status are updated to running.
106+
107+
### Volume Sync
108+
109+
- `syncWorkflowVolumes` prepares remote directories.
110+
- It copies workflow data to the cluster and later pulls results back.
111+
- This is the critical relation between workflow volumes and remote execution.
112+
113+
### Verification
114+
115+
- `VerifyActivitiesWasFinished` checks each running activity.
116+
- It reads remote completion state and job status.
117+
- If the job is complete or failed, it syncs volumes back and closes the activity.
118+
119+
## Kubernetes Runtime
120+
121+
### Main classes
122+
123+
- `KubernetesRuntime`
124+
- `KubernetesRuntimeService`
125+
- `ModeRunActivityService`
126+
- `MonitorVerifyActivityWasFinishedService`
127+
- `MonitorGetLogsActivityService`
128+
- `MonitorGetMetricsActivityService`
129+
130+
### Execution
131+
132+
1. `KubernetesRuntime.ApplyJob` delegates to `KubernetesRuntimeService.ApplyJob`.
133+
2. The service loads activity and workflow records.
134+
3. It resolves the workflow mode.
135+
4. The mode-specific service prepares Kubernetes resources.
136+
5. The job is applied in the cluster.
137+
138+
### Monitoring
139+
140+
- `VerifyActivitiesWasFinished` delegates to a monitor service.
141+
- `GetLogs` and `GetMetrics` delegate to dedicated monitor services.
142+
- `HealthCheck` validates the runtime and discovers nodes.
143+
144+
## Docker Runtime
145+
146+
- Docker exists in the runtime factory.
147+
- It behaves like a placeholder compared to the other runtimes.
148+
149+
## Relationship Summary
150+
151+
- Entities define workflow state.
152+
- Repositories store workflow state.
153+
- Connectors perform external I/O.
154+
- Runtime services coordinate everything.
155+
- Runtime wrappers only adapt to the common interface.
156+
157+
## AI Guidance
158+
159+
- When tracing a bug, start with the runtime wrapper, then the runtime service, then the connector and repositories.
160+
- For persistence bugs, inspect mount path handling first.
161+
- For execution bugs, inspect runtime selection and activity state transitions first.

‎.github/ai/CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Claude Notes For Akoflow
2+
3+
Read `AGENTS.md` first.
4+
5+
Use `AI_ARCHITECTURE.md` for the overall system map and `AI_RUNTIME_EXECUTION_FLOW.md` for runtime-specific behavior.
6+
7+
## Claude Usage Style
8+
9+
- Prefer the shared architecture file for broad questions.
10+
- Prefer the runtime flow file when tracing execution bugs.
11+
- Keep changes minimal and avoid unrelated edits.

‎.github/ai/CODEX.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Codex Notes For Akoflow
2+
3+
Read `AGENTS.md` first.
4+
5+
The shared source of truth is split into:
6+
7+
- `AI_ARCHITECTURE.md`
8+
- `AI_RUNTIME_EXECUTION_FLOW.md`
9+
10+
## Codex Focus
11+
12+
- Use the architecture file to understand package relationships.
13+
- Use the runtime flow file to understand execution per runtime.
14+
- Treat mount-path handling as a first-class concern for Singularity and HPC.

0 commit comments

Comments
 (0)