Back to docs

Guía de Desarrollo de Features (Ejemplo: Integración GitHub)

title: Feature Guide

--- title: Feature Guide description: Example guide for implementing features in Ekairos Core. ---

Guía de Desarrollo de Features (Ejemplo: Integración GitHub)

Esta guía documenta las convenciones, arquitectura y pasos para implementar una nueva feature en ekairos-core, utilizando la Integración de GitHub como caso de estudio.

1. Arquitectura

La arquitectura de ekairos-core se basa en:

  • **Domain-Driven Design (DDD)**: Lógica encapsulada en src/lib/domain/<context>.
  • **InstantDB**: Base de datos reactiva y en tiempo real.
  • **Clerk**: Autenticación y gestión de organizaciones.
  • **Next.js App Router**: UI y API Routes.
  • **Server-Only Services**: Servicios que ejecutan lógica de negocio en el backend.

Estructura de Directorios

src/
├── app/
│   ├── api/                  # Endpoints HTTP (delgados)
│   │   └── integration/      # Agrupados por dominio
│   │       └── github/
│   ├── platform/             # UI de la plataforma
│   └── code/                 # UI específica de Coding Agent
├── lib/
│   ├── domain/               # Lógica de negocio
│   │   ├── integration/      # Dominio de Integraciones
│   │   │   ├── schema.ts     # Esquema de InstantDB
│   │   │   └── github/       # Módulo específico
│   │   │       ├── constant.ts
│   │   │       ├── service.ts
│   │   │       └── oauth/
│   │   └── ...
│   ├── admin-org-db.ts       # Helper para DB admin per-org
│   └── client-org-db.ts      # Helper para DB client per-org
└── components/               # Componentes reutilizables

2. Convenciones de Dominio

Schema

  • Usar prefijos para entidades: integration_externalConnections, integration_secrets.
  • Definir relaciones (links) claras en schema.ts.
  • Incluir dominios en src/lib/domain.ts.

Permisos (instant.perms.ts)

  • secrets siempre view: "false".
  • Restringir acceso por organización: "auth.id in data.ref('organization.members.id')".

Servicios

  • **Server-Only**: Usar import "server-only" al inicio.
  • **Inyección de Dependencias**: Preferir pasar clerkOrgId y obtener adminDb dentro del método o constructor usando getOrgAdminDb.
  • **Resultados**: Retornar ServiceResult<T> = { ok: true, data: T } | { ok: false, error: string }.

3. Implementación Paso a Paso

Fase 1: Definición de Datos

  1. Definir entidades en lib/domain/<domain>/schema.ts.
  2. Configurar reglas de seguridad en instant.perms.ts.

Fase 2: Lógica de Negocio (Servicios)

  1. Crear constantes en constant.ts (URLs, Env Vars).
  2. Implementar servicios de OAuth (si aplica) para manejar tokens.
  3. Implementar servicios de lógica principal (ej: GitHubIntegrationService).
  • Usar SandboxService para operaciones de sistema/git.

Fase 3: API Routes

  1. Crear endpoints delgados en app/api/....
  2. Validar auth() de Clerk.
  3. Delegar a servicios.
  4. Para procesos largos (CLI), usar Server-Sent Events (SSE).

Fase 4: UI y Componentes

  1. Crear componentes visuales en app/platform/... o components/....
  2. Usar **Neo-Brutalism** (bordes definidos, fuentes mono, uppercase headers).
  3. Usar useOrgDb para leer datos reactivos de InstantDB.

4. Caso de Estudio: GitHub

Flujo OAuth (PKCE)

  1. **Auth URL**: GET /api/integration/github/auth-url -> Genera state/PKCE, guarda en DB, redirige a GitHub.
  2. **Callback**: GET /api/integration/github/callback -> Valida state, intercambia code por token, guarda en integration_secrets.

Flujo DevOps (CLI)

  1. **Endpoint SSE**: /api/devops/github/cli-run.
  2. **Sandbox**: Se crea un sandbox temporal o persistente.
  3. **Comandos**: git clone, git checkout, etc. ejecutados vía SandboxService.runCommand.
  4. **Feedback**: Eventos stdout, stderr, progress enviados al cliente.

5. Checklist de Calidad

  • [ ] pnpm lint sin errores.
  • [ ] pnpm type-check sin errores.
  • [ ] Secretos no expuestos al cliente.
  • [ ] Validación de orgId en todas las operaciones.