Infrastructure

Document generated from reading the github.com/adapta-school organization (≈40 repositories, all private except the *-releases). Starting point: adapta-one-agent is a full-stack Next.js app — the web frontend and the backend (API routes) live in the same repo, and this same API is consumed by adapta-one-mobile. From there we mapped the remaining product and infrastructure repositories.

Read date: 2026-06-24.

1. Block overview (by subsystem)

The organization contains four product lines + a cross-cutting infrastructure/automation layer:

2. Communication diagram — Adapta ONE ecosystem

Runtime communication connections between the subsystems. The arrows indicate who calls whom (direction of the request).

Summary of the main connections:

• adapta-one-mobile has no backend of its own — it talks to adapta-one-agent (agent.adapta.one) for agent resources, to adapta-one-agent-backend (api-agent.adapta.one) as the external backend, and to one-admin for the model catalog. It always sends Authorization: Bearer <Clerk token> + X-Client-Platform: mobile.
• adapta-one-agent is the hub: it serves the web UI, is the API for mobile/desktop, calls the microservices (RAG, sheet), the external backend, and the LLMs. It also syncs the Prisma schema to adapta-one-agent-backend and adapta-one-agent-chat-export (workflow sync-prisma-schema.yml).
• Several microservices call back to the central backend under different variable names: AGENT_BACKEND_URL, ADAPTA_ONE_AGENT_URL, ONE_API_BASE_URL, MAIN_SERVICE_URL, ONE_BACKEND_URL.
• Auth is cross-cutting: Clerk across almost the entire ecosystem (exception: one-admin uses Better Auth).
• Redis is the common broker (BullMQ in scheduler and deep-research); PostgreSQL via Prisma is the standard database for the Node services; vector storage in Qdrant/Astra.

3. Infrastructure & deployment diagram (whole org)

How code becomes production. There are two deployment patterns that coexist.

Map of "how each repo is delivered"

AWS layer (provisioned by iac-terraform, primary region sa-east-1, account 720035686972): EKS, ~15 ECR repositories, RDS (dedicated Aurora + Postgres: credits, notification, one-admin, wizard…), DynamoDB, S3, SQS, KMS, CloudFront, WAF, Lambda, Route53/ACM/SES, and the OIDC role github-actions-org-adapta-school that CI assumes. In-cluster layer (iac-kubernetes via ArgoCD): cert-manager, ingress-nginx, AWS ALB, Envoy Gateway, external-secrets, Karpenter, Velero, Datadog, Redis operator, and the n8n stack (DEV/PROD) on the marketing cluster (us-east-1).

4. Per-repository blocks (quick reference)

Adapta ONE line (clients)

• adapta-one-agent — Next.js 16 / React 19, full-stack (front + ~235 API routes). Ecosystem hub. Clerk auth, Prisma/Postgres, Vercel AI SDK, Redis/Upstash, QStash, Qdrant. Deploy via Vercel. CI: quality-checks (typecheck/lint/test/Sonar) + Lighthouse + Prisma schema sync.
• adapta-one-mobile — Expo SDK 55 / RN 0.83. Mobile client; consumes adapta-one-agent + adapta-one-agent-backend + one-admin. Clerk + Apple Auth, RevenueCat, Amplitude, Sentry. EAS build + OTA (no GitHub Actions).
• adapta-one-agent-desktop (+ -releases) — Electron 28/React 18 "Adapta ONE 26". Consumes the API, the external backend, and the wizard-backend. Release via electron-builder → releases repo.
• adapta-one / adapta-one-global — earlier Next.js 14 frontends of the product (Vercel). adapta-one connects to the agent-backend via NEXT_PUBLIC_API_AGENT_URL.
• one-admin — Next.js 16, admin panel for the model catalog consumed by web/mobile/desktop. Better Auth, Prisma/Postgres, publishes the catalog to Vercel Edge Config.
• adapta-chroma — despite the name, it is not a vector DB: it is the admin back-office (companies/users/licenses/announcements/analytics). Next.js 15, Clerk, Prisma, Sanity, S3, BigQuery. Deploy via Vercel.
• opera-ui — shared design system (@adapta-school/opera-ui), shadcn/ui + Storybook, published to GitHub Packages.

ONE backends (Fastify/Mastra, EKS)

• adapta-one-agent-backend — active backend (api-agent.adapta.one). Fastify + Mastra, Prisma/Postgres, Redis, BullMQ, Astra/Qdrant, S3. Calls RAG and Sheet.
• adapta-one-backend — legacy/established backend (one-backend). Almost identical stack; extra integrations (MercadoPago, Cademi, HubSpot, WhatsApp).
• adapta-one-agentic-backend — lean prototype (Bun + Fastify + Mastra), agent memory in Postgres.

ONE microservices

• adapta-one-document-rag — RAG/OCR/PPT (Fastify, Reducto, Textract, LangChain). EKS.
• adapta-one-sheet-services — spreadsheet analysis (FastAPI + pandas + OpenAI). EKS.
• adapta-one-document-services — document rerank/split (FastAPI + sentence-transformers). Docker/Procfile.
• adapta-one-youtube-services — YouTube video transcription (FastAPI). Docker/Procfile.
• adapta-one-agent-credits-service — credits service (Fastify + Prisma + Clerk). EKS.
• adapta-one-agent-chat-export — SQS worker: exports chats, decrypts, S3 + email. EKS.
• adapta-one-agent-notification — announcements/notifications (Fastify + Clerk + S3/CloudFront). EKS.
• adapta-one-scheduler-service — BullMQ scheduler (Outlook/Paragon, post-meeting actions). EKS.
• adapta-deep-research — asynchronous deep research (BullMQ worker + WS gateway, Firecrawl, AI SDK). Docker (no GH Actions). ⚠️ Redis Cloud credentials committed in docker-compose.yml.
• mobile-voice-chat-server — WebSocket proxy for voice/realtime (OpenAI Realtime + Gemini). Plain Node.
• revenuecat-webhook — RevenueCat subscription webhook → provisions licenses in one-backend. Plain Node.
• adapta-internal-services — user provisioning + Cademi/Resend integration (Fastify + Clerk + Prisma).

Adapta Wizard (formerly "Adapta Meetings")

• adapta-wizard (+ -releases) — Electron desktop for meeting capture/transcription/chat.
• adapta-wizard-backend — Express API dedicated to the Wizard (Prisma, Clerk, AssemblyAI, S3/KMS, Paragon). EKS. Also called by adapta-one-agent-desktop.

Adapta Plays

• adapta-plays — Next.js web product (Vercel). Astra vector, MeetGeek, scheduler, WhatsApp/WS.
• adapta-plays-scheduler-service — BullMQ jobs (Express + Redis).
• adapta-plays-sheet-service — spreadsheet processing (FastAPI).
• adapta-plays-webhook-test-microservice — webhook testing utility (WS + JWT).

Infra / CI-CD / Automation

• iac-terraform — Terraform + Terragrunt + Atlantis. Provisions the entire AWS base (EKS, ECR, RDS, S3, SQS, IAM/OIDC, DNS, CloudFront). State in S3 + DynamoDB lock.
• iac-kubernetes — ArgoCD GitOps (App-of-Apps + ApplicationSet matrix). Add-ons, operators, and the n8n stack. Auto-sync with prune + self-heal.
• github-actions-workflows — library of reusable workflows (create-release, build-image-to-ecr, scan-analyze, deploy-argocd). It is the org's CI/CD standard.
• n8n-pipeline — control plane that promotes n8n workflows from DEV (flow-dev.adaptahub.org) to read-only PROD (flow.adaptahub.org). Deployed via Pattern B.
• n8n-workflows-src — GitOps store of workflow artifacts (workflow.json + manifest.json + history/).
• adapta-one-product-ops — standalone Python script to categorize feedback (OpenAI). No deploy.

5. Local development quick start

Common prerequisites: Node (use each repo's .nvmrc), pnpm (ONE apps) or npm (mobile), Docker (microservices/Postgres), and the variables from .env.example/.env. Auth via Clerk requires dev keys. Do not commit secrets.

adapta-one-agent (web + API — the hub)

cd adapta-one-agent
nvm use                      # Node 22.18.0
pnpm install
pnpm prisma:generate         # gera o client Prisma
cp .env.example .env         # preencha CLERK_*, DATABASE_URL, REDIS_URL, AI_GATEWAY_API_KEY, etc.
pnpm dev                     # Next.js em http://localhost:3000
# qualidade: pnpm typecheck && pnpm lint && pnpm test

adapta-one-mobile (Expo / React Native)

cd adapta-one-mobile
nvm use
npm install
cp .env.example .env         # EXPO_PUBLIC_API_URL=https://agent.dev.adapta.one
                             # EXPO_PUBLIC_EXTERNAL_BACKEND=https://api-agent-dev.adapta.one
                             # EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=...
npx expo start               # ou: npm run ios / npm run android

By default the app points to the remote dev environments (*.dev.adapta.one). To run against a local backend, point EXPO_PUBLIC_API_URL to your adapta-one-agent (use the LAN IP, not localhost, on a physical device).

Backends (adapta-one-agent-backend / adapta-one-backend)

cd adapta-one-agent-backend
pnpm install
pnpm prisma generate
cp .env.example .env         # CLERK_*, DATABASE_URL (Postgres), REDIS_URL, chaves de LLM
docker compose up -d         # quando houver compose (Postgres/Redis locais)
pnpm dev                     # Fastify

Python microservices (sheet / document / youtube)

cd adapta-one-sheet-services
python3.9 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8080   # OPENAI_API_KEY / AWS_* no ambiente

Node microservices with a queue (scheduler-service, deep-research)

cd adapta-one-scheduler-service
npm install
docker compose up -d redis   # backend do BullMQ
cp .env.example .env         # REDIS_URL, ONE_API_BASE_URL, JWT_SECRET
npm run dev                  # dashboard Bull Board em /admin/queues

Desktop apps (Electron)

cd adapta-one-agent-desktop   # ou adapta-wizard
pnpm install
cp .env.example .env          # RENDERER_API_URL, MAIN_CLERK_*, etc.
pnpm dev

Infra

# iac-terraform (NÃO aplica em prod localmente — use Atlantis via PR)
cd iac-terraform/cloud/aws/.../<env>/.../<service>
terragrunt plan

# iac-kubernetes — é declarativo; valide o chart localmente
helm dependency build <path-do-chart> && helm template <path-do-chart>

6. CI/CD — what happens after a PR is merged into main

There are two flows depending on the repository type.

Flow A — Next.js frontends (Vercel)

Repos: adapta-one-agent, adapta-one, adapta-one-global, one-admin, adapta-chroma, adapta-plays.

1. PR opened → the quality CI runs (in adapta-one-agent: quality-checks-standards.yml → prisma:generate, typecheck, lint, test:coverage, SonarQube + quality gate, pnpm audit; plus Lighthouse).
2. Merge into the environment branch (development / production) → Vercel's Git integration detects the push and performs an automatic build + deploy (no deploy GitHub Actions). vercel.json defines the functions' maxDuration (up to 800s for streaming).
3. adapta-one-agent also triggers sync-prisma-schema.yml on merge, propagating the Prisma schema to adapta-one-agent-backend and adapta-one-agent-chat-export.

There is no image promotion: Vercel creates preview deployments per PR and promotes the build from the production branch.

Flow B — Containerized services (ECR → ArgoCD → EKS)

Repos: all backends/microservices with chart/ + .github/workflows/ci-*.yaml (e.g.: adapta-one-agent-backend, -credits-service, -chat-export, -notification, -document-rag, -sheet-services, scheduler-service, adapta-wizard-backend, n8n-pipeline).

Each repo calls the reusable workflows from adapta-school/github-actions-workflows@vX.Y.Z. The chain after the push to the environment branch (develop / staging / production):

Step by step:

1. Trigger — a push to the environment branch (develop/staging/production) triggers ci-<env>.yaml. Docs-only changes are ignored.
2. create-release — computes the next semver (semver-release-action) and creates a GitHub Release/tag; produces the release-tag used as the image tag and as the revision in ArgoCD.
3. build-image-to-ecr — authenticates to AWS via OIDC (role github-actions-org-adapta-school, no static credentials), runs docker buildx (cross-build arm64/Graviton) and pushes the image to ECR (account 720035686972), with tags :latest and :<release-tag>, injecting Datadog Git metadata.
4. scan-analyze (optional) — SonarQube (the scheduler-service, for example, skips this step).
5. deploy-argocd — via the ArgoCD CLI against argocd.foundation.management.adapta.tools: argocd app create --upsert pointing to the app's own repo (path chart/, revision=<release-tag>, --values values-<env>.yaml, --helm-set image.tag=<release-tag> and run_migrations), followed by argocd app sync (or letting auto-sync act).
6. ArgoCD reconciles on EKS: it renders the Helm with the new tag, runs migrations via Helm hooks, and brings up the pods on Graviton/ARM64 nodes autoscaled by Karpenter, behind ALB/ingress-nginx/Envoy, using RDS/Redis/S3/SQS and secrets via external-secrets, with Datadog observability.

Base provisioned separately: infra changes (clusters, ECR, RDS, IAM, DNS) live in iac-terraform and follow PR → Atlantis (plan/apply by comment). In-cluster platform changes (add-ons, operators, n8n stack) live in iac-kubernetes and are applied by ArgoCD auto-sync (App-of-Apps + ApplicationSet) — with no image pipeline.

Other release flows

• Desktop (Electron) — mac-release.yml / windows-release.yml run electron-builder, sign and publish artifacts to the *-releases repos; clients receive them via auto-update.
• Mobile (Expo) — no GitHub Actions: releases via EAS Build + store submit, and fixes via EAS Update (OTA); both triggered manually by the npm scripts.
• opera-ui — ci-cd.yml with semantic-release publishes the npm package to GitHub Packages.
• n8n — n8n-pipeline promotes workflows (not an image) from DEV→PROD and versions them in n8n-workflows-src. The n8n-custom image bump is manual in iac-kubernetes.

7. Notes and points of attention

• adapta-chroma ≠ vector database — it is a Next.js admin panel; the name is misleading.
• adapta-one-agent-notification — the README is a mistaken copy of chat-export's; the code/package.json is the correct source.
• ⚠️ adapta-deep-research — docker-compose.yml contains a Redis Cloud connection string with committed credentials; it is recommended to rotate it and move it to secrets.
• master branch in docs — several READMEs cite master for ArgoCD/Atlantis, but the real default is main (and ArgoCD uses revision: HEAD). Outdated documentation.
• Backend convergence — adapta-one-backend (legacy), adapta-one-agent-backend (active), and adapta-one-agentic-backend (prototype) share the package name adapta-one-backend, indicating evolution from a common template.