Authexis · Codebase

Overview

Authexis is an AI content production platform. The system has four physical tiers:

Web

Next.js 15 · Vercel

App UI, marketing site, REST API. Server actions handle mutations; route handlers cover public + internal APIs.

Engine

Python · Railway

AI generation, pipelines, job handlers. Invoked by Supabase edge functions or cron. One handler per job type.

Database

Supabase · PostgreSQL

Auth, data, realtime, RLS. Shared between dev and prod (see DECISIONS). Migrations are the schema source of truth.

Apple

SwiftUI · Universal

iOS / iPadOS / macOS via Supabase direct access. 94 Swift files in the main target plus widgets and a share extension.

Structure

Top-level directories and what lives in each.

web/                    — Next.js 15 app (frontend + API routes)
  actions/              — server actions (business logic entry points)
  app/(app)/            — authenticated app routes (dashboard, feeds, scans, etc.)
  app/(auth)/           — login/signup flows
  app/api/              — REST API routes (v1/ public, v2/ internal, webhooks, ingest)
  components/           — shared React components
  lib/                  — utilities (supabase clients, stripe, posthog)

engine/                 — Python engine (AI jobs, pipelines)
  engine/handlers/      — job handlers (one file per job type)
  engine/services/      — shared services (claude, discord, bluesky, etc.)
  engine/prompts/       — prompt templates (outbound/, content/, etc.)
  scripts/              — utility scripts

supabase/
  migrations/           — SQL migrations (source of truth for schema)

apple/                  — Universal Apple app (iOS/iPadOS/macOS, SwiftUI)
  Authexis/             — Main app target (94 Swift files)
    Features/           — Content, dashboard, settings views
    Navigation/         — Router, sidebar, tab views
    Managers/           — NotificationManager, NotificationStore
    Services/           — API client, auth, Supabase direct access
  ShareExtension/       — Share sheet for quick reactions
  AuthexisWidgets/      — Home screen widgets (review count, dashboard, briefing)
ios/                    — LEGACY — old iOS-only target, superseded by apple/

Key files

The doors into the codebase. When in doubt, start here.

File	What it is
`PRODUCT.md`	Product vision, personas, pricing
`DECISIONS.md`	Architectural and product decisions log
`CHANGELOG.md`	User-facing change history (Keep a Changelog format)
`ROADMAP.md`	Quarterly roadmap
`web/actions/*.ts`	Server actions — most business logic starts here
`engine/engine/handlers/*.py`	Job handlers — each handles one job type
`supabase/migrations/`	Database schema (read recent ones for current state)

Patterns

Web: Next.js App Router, server actions for mutations, Supabase for auth + data.
Engine: Python handlers invoked by Supabase edge functions or cron. Each handler is a standalone module.
Database: Supabase (PostgreSQL). Shared between dev and prod. Migrations are the schema source of truth.
No Rails trap: archive/rails/ is a dead legacy app. Ignore it entirely.
No .rb files trap: This is a TypeScript + Python project. Never search for Ruby files.

Ignore these directories

Skip these when scouting, scanning, or scoping work — none of them carry source-of-truth code:

archive/ · node_modules/ · .next/ · build-mac/ · SourcePackages/ · vendor/ · dist/ · build/ · backup/