Aexy
Get Started

Tech Stack

Technologies and frameworks used

Overview#

Aexy is a full-stack Engineering OS — a Next.js frontend talking to a FastAPI backend, with Temporal driving every background workflow and Microsoft Graph / Google APIs / Slack / Stripe / GitHub / Anthropic / Gemini wired in as integrations.

Backend#

Core Framework#

TechnologyVersionPurpose
Python3.13Primary language
FastAPI0.109+Web framework
Pydantic2.5+Data validation
SQLAlchemy2.0+ORM (async via asyncpg, sync via psycopg2)

Database migrations use a custom SQL system (backend/scripts/migrate_*.sql + schema_migrations table). Alembic is installed as a transitive dependency but is not used.

Database & Storage#

TechnologyVersionPurpose
PostgreSQL18Primary database (+ pgvector for embeddings)
Redis7Cache, sessions, LLM rate limiting
RustFS—S3-compatible object storage for uploads

Background Processing#

TechnologyPurpose
TemporalWorkflow engine — replaces Celery/Beat/APScheduler
temporalio SDKPython client and worker
croniterCron expression parsing for schedules

Activities live in aexy/temporal/activities/, workflows in aexy/temporal/workflows/, periodic schedules in aexy/temporal/schedules.py. The worker is python -m aexy.temporal.worker.

AI / LLM#

TechnologyPurpose
Anthropic ClaudePrimary LLM provider
Google GeminiAlternate LLM provider
OllamaLocal/OSS LLM provider
LangGraph + LangChainAgent orchestration (aexy/agents/)

All providers sit behind aexy/llm/gateway.py. Rate limiting is Redis-based; LLMRateLimitError triggers a Temporal retry.

Authentication#

TechnologyPurpose
JWT (python-jose)API tokens
GitHub OAuthSign-in
Google OAuthSign-in + Gmail/Calendar
Microsoft Graph OAuth 2.0Sign-in + Outlook/Calendar
passlib (bcrypt)Password hashing

External Integrations#

IntegrationAPI TypePurpose
GitHubREST + Webhooks + GitHub AppSource code data
Google WorkspaceRESTGmail + Calendar + People
Microsoft GraphRESTOutlook + Calendar + Teams
SlackREST + EventsNotifications, slash commands
StripeREST + WebhooksSubscription billing
TwilioRESTSMS
Web Push (VAPID)—Browser push notifications
AWS SES / SMTP—Outbound email

Frontend#

Core Framework#

TechnologyVersionPurpose
Next.js14 (App Router)React framework
React18UI library
TypeScript5+Type safety

State & Data#

TechnologyPurpose
ZustandGlobal client state
@tanstack/react-queryServer-state fetching, caching, invalidation

Styling#

TechnologyPurpose
TailwindCSSUtility-first CSS
Radix UIAccessible primitives
Lucide IconsIcon library
clsxConditional classes

Internationalisation#

TechnologyPurpose
next-intli18n (App Router integration, cookie-based locale)

Testing (frontend)#

TechnologyPurpose
VitestUnit tests
PlaywrightEnd-to-end tests

Mailagent (Email Infrastructure Microservice)#

Separate FastAPI service that handles email domain management, SPF/DKIM/DMARC verification, warming, and inbox administration. Runs on port :8001. Same tech stack as the main backend (FastAPI + SQLAlchemy + Temporal).

CLI Tool#

TechnologyPurpose
Python 3.11+Language
ClickCLI framework
RichTerminal formatting
httpxHTTP client
keyringCredential storage

VS Code Extension#

TechnologyPurpose
TypeScriptLanguage
VS Code Extension APIExtension framework

Development Tools#

Code Quality#

ToolPurpose
RuffPython lint + format
mypyPython type checking
ESLintTypeScript linting
PrettierCode formatting

Testing (backend)#

ToolPurpose
pytestTest framework
pytest-asyncioAsync test support
pytest-covCoverage reporting
aiosqliteSQLite-backed test DB (note: some PostgreSQL-specific behaviours don't surface in tests)

Infrastructure#

Deployment#

OptionPurpose
DockerContainerization
Docker ComposeLocal development + single-host prod (docker-compose.prod.yml)
nginxTLS termination, /storage/ → RustFS proxy

Default ports#

ServicePort
Backend (FastAPI)8000
Frontend (Next.js)3000
Mailagent8001
Temporal UI8080
Temporal server7233
PostgreSQL5432
Redis6379
RustFS9000

Version Compatibility Matrix#

ComponentMinimumRecommended
Python3.133.13
Node.js1820 LTS
PostgreSQL16 (with pgvector)18
Redis67
Temporal server1.22latest

Environment Configuration#

The full set is documented in .env.prod.example; the most load-bearing variables:

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/aexy

# Redis
REDIS_URL=redis://localhost:6379/0

# Temporal
TEMPORAL_ADDRESS=temporal:7233

# Auth
SECRET_KEY=...  # openssl rand -hex 32
JWT_ALGORITHM=HS256

# LLM (pick one default)
LLM_PROVIDER=gemini       # or claude / ollama
LLM_MODEL=gemini-2.0-flash
GEMINI_API_KEY=...
# ANTHROPIC_API_KEY=...

# Object storage (S3 / RustFS)
RUSTFS_ROOT_USER=...
RUSTFS_ROOT_PASSWORD=...
S3_PUBLIC_ENDPOINT_URL=https://server.aexy.io/storage

# OAuth providers
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
MICROSOFT_CLIENT_ID=...
MICROSOFT_CLIENT_SECRET=...
MICROSOFT_TENANT_ID=common

See Microsoft integration, Google integration, and the booking/slack/stripe docs for provider-specific setup.

Package Dependencies#

Backend dependencies are pinned in backend/pyproject.toml. Highlights (excerpt — see the file for the complete list):

dependencies = [
    "fastapi>=0.109.0",
    "uvicorn[standard]>=0.27.0",
    "sqlalchemy>=2.0.0",
    "asyncpg>=0.29.0",
    "psycopg2-binary>=2.9.0",
    "pydantic[email]>=2.5.0",
    "pydantic-settings>=2.1.0",
    "httpx>=0.26.0",
    "python-jose[cryptography]>=3.3.0",
    "passlib[bcrypt]>=1.7.4",
    "anthropic>=0.40.0",
    "langgraph>=0.2.0",
    "langchain>=0.3.0",
    "langchain-anthropic>=0.2.0",
    "langchain-google-genai>=2.0.0",
    "twilio>=9.0.0",
    "pywebpush>=2.0.0",
    "aiosmtplib>=3.0.0",
    "boto3>=1.34.0",
    "jinja2>=3.1.0",
    "redis>=5.0.0",
    "croniter>=2.0.0",
    "temporalio>=1.9.0",
    "stripe>=7.0.0",
    "PyJWT>=2.8.0",
    "openpyxl>=3.1.0",
    "pgvector>=0.3.0",
    "pypdf>=5.0.0",
    "python-docx>=1.1.0",
]

Frontend dependencies are pinned in frontend/package.json — Next.js 14, React 18, Tailwind 3, Zustand, React Query, Radix UI, next-intl, Vitest, Playwright.

PreviousSystem ArchitectureNextDatabase Schema