Skip to main content

Architecture overview

A map of everything in the eigenoid org: repositories, technologies, environments, and how they connect.

Organization overview​

Eigenoid is a private GitHub organization building an AI agent framework. The org contains the core framework, supporting applications, backend services, infrastructure-as-code, platform tooling, and documentation. All repositories are private.

The repository naming convention uses category prefixes (app-, svc-, iac-, docs-, platform-) so you can identify a repo's purpose from its name alone.

Repository map​

Repository details​

Core Framework​

RepositoryStackPurpose
eigenoidPython, CythonAI agent framework with SPIFFE/SPIRE identity and delegation chains. Distributed as compiled wheels via Artifact Registry.
eigenoid-samplePythonReference implementation of the automated distribution pipeline. Used to validate the packaging, tagging, and release flow.

Applications​

RepositoryStackPurpose
app-access-adminReact, Vite, TypeScriptInternal admin portal for access management. Behind Cloudflare Access (GitHub org auth).
app-access-publicReact, Vite, TypeScriptPublic-facing portal for access management. Magic link + MFA (TOTP, Passkeys, Email OTP backup) authentication. Runs on Cloudflare Workers.
app-block-pageHTML/CSS, Cloudflare PagesCustom block page shown when Cloudflare Access denies a request. See ADR-0005.
app-studio-frontendReact, Vite, TypeScriptVisual agent builder UI for designing and testing multi-agent systems.

Backend Services​

RepositoryStackPurpose
svc-accessGo, Chi, GORM, PostgreSQLBackend API for the access management product. Runs on Cloud Run with separate admin and public modes.
svc-studioGoGo backend for the Studio product (workflow/automation engine). Runs on Cloud Run.

Infrastructure​

All infrastructure repos use Terraform targeting Google Cloud Platform, following the producer/consumer model.

RepositoryPurpose
iac-foundationWorkload Identity Federation, service accounts, GCP API enablement
iac-platformCloud Run deployments, Artifact Registry
iac-accessAccess product infrastructure: Cloud Run, tunnels, DNS, Access apps
iac-api-gatewayTerraform for Apigee API Gateway resources
iac-studioTerraform for Studio domain (svc-studio + frontend)
iac-distributionArtifact Registry repositories for Python packages (one per project)
iac-templatePre-configured template for bootstrapping new IaC stacks

Platform Tooling​

RepositoryStackPurpose
platform-actionsGitHub Actions, YAMLReusable workflows, Terraflow orchestrator, centralized environment config
platform-api-gatewayCloudflare Workers, TypeScriptAPI routing layer with domain separation (.eigenoid.services internal, .eigenoid.com public). See API Gateway docs.
platform-design-tokensTailwind CSSShared design token preset consumed by all frontend applications
platform-settingsYAML, GitHub Actionssafe-settings configuration for GitHub org governance. See ADR-0006.

Documentation​

RepositoryStackPurpose
docs-internalDocusaurus 3, TypeScriptThis site. Private internal documentation at docs.eigenoid.services.
docs-externalDocusaurus 3, TypeScriptPublic-facing documentation.

Technology landscape​

CategoryTechnologies
LanguagesTypeScript, Go, Python, Cython, HCL
FrontendReact, Vite, React Flow, Tailwind CSS, Cloudflare Workers (Workers Builds)
BackendGo (Chi router, GORM ORM), PostgreSQL (Cloud SQL)
AI / IdentitySPIFFE/SPIRE, delegation chains
InfrastructureTerraform, Google Cloud Platform (Cloud Run, Cloud SQL, Artifact Registry, WIF)
Edge / CDNCloudflare (Pages, Workers, Access, Tunnels, DNS)
CI/CDGitHub Actions, Terraflow (custom orchestrator), Cloudflare Pages (docs)
Governancesafe-settings (GitHub App), Conventional Commits, squash merge
DocumentationDocusaurus 3, Mermaid diagrams, ADRs

Environment topology​

The org operates three isolated GCP projects, one per environment, as defined in ADR-0009. Cloudflare handles the edge layer. GitHub is the source of truth for code and CI.

LayerServiceRole
Source + CIGitHubCode hosting, pull request workflows, GitHub Actions for build/test/deploy
EdgeCloudflare PagesStatic hosting for documentation and block page
EdgeCloudflare WorkersAPI gateway (request routing, header sanitization) and frontend app hosting via Workers Builds (app-access-public, app-studio-frontend)
EdgeCloudflare AccessZero Trust authentication (GitHub org for internal, magic link for public)
EdgeCloudflare TunnelsSecure origin connectivity -- backends are never exposed directly
ComputeCloud RunContainerized backend services (Go) with per-environment isolation
DataCloud SQL (PostgreSQL)Managed relational database, one instance per environment
ArtifactsArtifact RegistryPython packages and Docker images, one repository per environment
AuthWorkload Identity FederationKeyless CI authentication from GitHub Actions to GCP via OIDC

All regional GCP resources use europe-west1 (Belgium). Environment configuration is centralized in platform-actions/config/environments.yaml.

Data flow​

How a typical request travels from user to database and back.

  1. The user hits a frontend URL (e.g., access-dev.eigenoid.services).
  2. Cloudflare Access authenticates the request. Internal apps use GitHub OAuth (org membership required). Public apps use magic link + MFA (TOTP, Passkeys, Email OTP).
  3. Cloudflare Workers serves the frontend apps.
  4. The frontend makes API calls to the gateway domain (e.g., api-dev.eigenoid.services).
  5. The Cloudflare Worker validates and sanitizes headers, then forwards the request through a Cloudflare Tunnel using a service token.
  6. The tunnel routes to the appropriate Cloud Run instance (svc-access in admin or public mode).
  7. The Go backend processes the request, queries Cloud SQL (PostgreSQL), and returns the response back through the same chain.

System jobs (Cloud Scheduler, Pub/Sub) bypass the gateway and call Cloud Run directly.

Next steps​