Skip to content
This repository was archived by the owner on Feb 24, 2026. It is now read-only.

CLAUDE.md

Latest commit

 

History

History
501 lines (411 loc) · 15.8 KB

CLAUDE.md

File metadata and controls

501 lines (411 loc) · 15.8 KB

Ovrly Monorepo

Quick Reference: Where Is Everything?

Apps

App Type Location Purpose
ovrly_photo Flutter ovrly/apps/ovrly_photo/ Main iOS app - camera overlay alignment (launching first)
ovrly_draw Flutter ovrly/apps/ovrly_draw/ Drawing app skeleton (future)
ovrly_web Next.js ovrly/apps/ovrly_web/ Basic website, legal docs, universal links
admin Next.js admin/ Admin dashboard for overlays, notifications, videos

Shared Packages

Package Location Purpose
ovrly_core ovrly/packages/ovrly_core/ Models, services, providers, auth, API client
ovrly_shaders ovrly/packages/ovrly_shaders/ GLSL shaders for Flutter and Python

Infrastructure (AWS CDK)

Stack Location Purpose
los-api ovrly/infrastructure/los-api/ Main API: Lambda, DynamoDB, Cognito, S3
los-prod-iam ovrly/infrastructure/los-prod-iam/ Production IAM policies

Naming History

Current brand: Ovrly (domain: ovrly.co)

Active CloudFormation Stacks (Dev)

  • OvrlyApiStack-Dev - Main API stack (current)
  • OvrlyDomainStack - Domain/DNS configuration

AWS Resource Naming

Most resources use ovrly-* naming now. Some legacy los-* and cirrae-* resources still exist but are being phased out.

Resource Type Current Pattern Legacy (may exist)
DynamoDB ovrly-photos-dev los-photos-dev
S3 ovrly-photos-dev los-photos-dev
Lambda OvrlyApiStack-Dev-* LinesOfSightDrawingsApiSt-*
Log Groups OvrlyApiStack-Dev-* LinesOfSightDrawingsApiSt-*

CDK infrastructure folder is still named los-api/ (local naming only, doesn't affect AWS).

Legacy Names Reference

  • los-* = "Lines of Sight" (original project name)
  • cirrae-* = intermediate brand name
  • LinesOfSightDrawingsApiSt-* = orphaned log groups from deleted stack

Directory Structure

/Users/jro/github/ovrly/
├── ovrly/                              # Main monorepo root
│   ├── apps/
│   │   ├── ovrly_photo/                # iOS photo app (main product)
│   │   │   ├── lib/                    # Flutter code
│   │   │   ├── ios/                    # iOS native
│   │   │   └── tool/                   # Python slideshow tools
│   │   ├── ovrly_draw/                 # Drawing app (skeleton)
│   │   └── ovrly_web/                  # Next.js website
│   ├── packages/
│   │   ├── ovrly_core/                 # Shared business logic
│   │   │   ├── lib/
│   │   │   │   ├── models/             # Freezed data classes
│   │   │   │   ├── providers/          # Riverpod state
│   │   │   │   ├── services/           # API, auth, geolocation
│   │   │   │   ├── repositories/       # Data access
│   │   │   │   ├── widgets/            # Shared UI
│   │   │   │   └── screens/            # Auth flows, demos
│   │   │   └── test/
│   │   └── ovrly_shaders/              # GLSL shader library
│   │       ├── core/                   # Platform-agnostic GLSL
│   │       ├── flutter/                # Flutter wrappers
│   │       └── opengl/                 # Python/OpenGL wrappers
│   ├── infrastructure/
│   │   └── los-api/                    # AWS CDK TypeScript
│   │       ├── lib/
│   │       │   ├── los-api-stack.ts    # Main stack
│   │       │   ├── ovrly-domain-stack.ts
│   │       │   └── constructs/
│   │       │       ├── OvrlyAuthSystem.ts  # Cognito auth
│   │       │       └── StandardLambda.ts
│   │       ├── lambda/
│   │       │   ├── auth/               # 17 auth functions
│   │       │   │   ├── signup/
│   │       │   │   ├── signin/
│   │       │   │   ├── passkeys/       # WebAuthn
│   │       │   │   └── ...
│   │       │   ├── domains/            # Business logic
│   │       │   │   ├── overlays/
│   │       │   │   ├── photos/
│   │       │   │   ├── videos/
│   │       │   │   ├── challenges/
│   │       │   │   └── ...
│   │       │   └── shared/             # Lambda layer
│   │       └── scripts/
│   ├── scripts/
│   ├── docs/
│   └── melos.yaml                      # Monorepo config
├── admin/                              # Admin dashboard (Next.js)
│   ├── app/                            # App router pages
│   │   ├── overlays/
│   │   ├── photos/
│   │   ├── videos/
│   │   ├── challenges/
│   │   ├── notifications/
│   │   └── links/
│   ├── components/
│   └── lib/
├── tools/                              # Utility scripts
├── match-repo/                         # iOS signing (submodule)
├── .github/workflows/                  # CI/CD
└── CLAUDE.md                           # This file

AWS Resources

Accounts:

Environment Account ID AWS Profile Stack
Development 014155356487 los-dev OvrlyApiStack-Dev
Production 396662537080 los-prod OvrlyApiStack-Prod

Always verify before AWS operations:

export AWS_PROFILE=los-dev   # or los-prod
aws sts get-caller-identity

Development Resources

Resource Name
API Gateway https://pc789w398e.execute-api.us-east-1.amazonaws.com/prod
Photos ovrly-photos-dev (DynamoDB + S3)
Overlays ovrly-overlays-dev (DynamoDB)
Overlay assets ovrly-overlay-assets-dev (S3)
User profiles ovrly-user-profiles-dev (DynamoDB)
Auth accounts ovrly-auth-user-accounts-dev (DynamoDB)
Pipeline jobs ovrly-pipeline-jobs-dev (DynamoDB + S3)
Videos ovrly-video-jobs-dev (DynamoDB), ovrly-generated-videos-dev (S3)

Production Resources

Resource Name
API Gateway https://i5kdtz8r46.execute-api.us-east-1.amazonaws.com/prod
Photos ovrly-photos-prod (DynamoDB + S3)
Overlays ovrly-overlays-prod (DynamoDB)
Overlay assets ovrly-overlay-assets-prod (S3)
User profiles ovrly-user-profiles-prod (DynamoDB)
Auth accounts ovrly-auth-user-accounts-prod (DynamoDB)
Pipeline jobs ovrly-pipeline-jobs-prod (DynamoDB + S3)
Videos ovrly-video-jobs-prod (DynamoDB), ovrly-generated-videos-prod (S3)

Note: Prod resources are clean ovrly-* naming. Dev has some legacy los-* resources that can be cleaned up.

Lambda Functions

Auth Functions (ovrly/infrastructure/los-api/lambda/auth/)

signup/           # User registration
signin/           # Email/password login
refresh/          # Token refresh
verify/           # Email verification
validate/         # Token validation
reset-password/   # Password reset flow
request-code/     # Verification codes
confirm-code/     # Code confirmation
delete-user/      # Account deletion
google-signin/    # Google OAuth
apple-signin/     # Sign in with Apple
link-provider/    # Link social accounts
unlink-provider/  # Unlink social accounts
passkeys/
  ├── challenge/  # WebAuthn challenge
  ├── register/   # Register passkey
  └── authenticate/ # Authenticate with passkey

Domain Functions (ovrly/infrastructure/los-api/lambda/domains/)

overlays/         # Overlay CRUD
photos/           # Photo management
videos/           # Video generation
challenges/       # User challenges
links/            # Deep links
admin/            # Admin operations
devices/          # Device registration
items/            # Generic items
pipeline/         # AI overlay pipeline
user/             # User profile

Development Setup

Flutter (FVM required)

# Flutter commands MUST use full path
/Users/jro/fvm/versions/3.35.0/bin/flutter analyze
/Users/jro/fvm/versions/3.35.0/bin/flutter test
/Users/jro/fvm/versions/3.35.0/bin/dart format .

# NEVER use bare 'flutter' or 'dart' commands
# NEVER run on macOS - iOS only, use Chrome for web testing

Melos (Monorepo)

cd ovrly
melos bootstrap          # Install all dependencies
melos analyze            # Lint all packages
melos test               # Run all tests
melos codegen            # Run build_runner
melos run shaders:generate  # Generate shader wrappers

CDK (Infrastructure)

cd ovrly/infrastructure/los-api
npm install
npm run build
cdk diff                 # See changes
cdk deploy               # Deploy stack

Admin Dashboard

cd admin
npm install
npm run dev              # Local dev server

Key Files Reference

Flutter/Dart

What File
Monorepo config ovrly/melos.yaml
Core package ovrly/packages/ovrly_core/pubspec.yaml
Photo app ovrly/apps/ovrly_photo/pubspec.yaml
API client ovrly/packages/ovrly_core/lib/services/api_service.dart
Auth service ovrly/packages/ovrly_core/lib/services/auth_service.dart
Photo providers ovrly/packages/ovrly_core/lib/providers/photo_providers.dart
Overlay model ovrly/packages/ovrly_core/lib/models/overlay.dart

Infrastructure

What File
Main CDK stack ovrly/infrastructure/los-api/lib/los-api-stack.ts
Auth construct ovrly/infrastructure/los-api/lib/constructs/OvrlyAuthSystem.ts
CDK config ovrly/infrastructure/los-api/cdk.json
Deploy script ovrly/infrastructure/los-api/deploy.sh

CI/CD

What File
Main CI .github/workflows/ci.yml
iOS TestFlight .github/workflows/ios-testflight-unified.yml
Admin CI .github/workflows/admin-ci.yml

Common Tasks

Find a Lambda function

# List all Lambda handlers
ls ovrly/infrastructure/los-api/lambda/auth/
ls ovrly/infrastructure/los-api/lambda/domains/

Find a Flutter model

# All Freezed models
ls ovrly/packages/ovrly_core/lib/models/

Find a provider

# All Riverpod providers
ls ovrly/packages/ovrly_core/lib/providers/

Find CDK constructs

ls ovrly/infrastructure/los-api/lib/constructs/

Check deployed resources

cd ovrly/infrastructure/los-api
cdk diff  # Shows what would change

Critical Rules

Git Policy

  • Commits: Fine anytime
  • Pushes: REQUIRE explicit user permission
  • Trunk-based: main only, tags for prod releases

Quality Standards

  • Never disable tests or linting to "fix" failures
  • Never use --no-verify
  • All tests must pass before declaring done
  • CI must be green = "working"

Platforms

  • iOS: Primary target (launching first)
  • Web: Secondary (Chrome for testing)
  • Android: Future (no support yet)
  • macOS: NEVER (not a target)

Technology Stack

Frontend:

  • Flutter 3.35.0 (FVM)
  • Riverpod (state)
  • Freezed (models)
  • Go Router (navigation)

Backend:

  • AWS CDK 2.x (TypeScript)
  • Lambda (Node.js 18)
  • DynamoDB
  • Cognito (auth)
  • S3 (storage)
  • API Gateway

Admin/Web:

  • Next.js 14
  • TypeScript
  • Tailwind + shadcn/ui

Video Generation:

  • Python 3.11
  • Modal.com (serverless)
  • FFmpeg
  • GLSL shaders

Environment Files

Canonical Values (Use These)

Development:

Variable Value
API_URL / API_BASE_URL https://ylod85pcfi.execute-api.us-east-1.amazonaws.com
USER_POOL_ID us-east-1_wYGP8aWYP
USER_POOL_CLIENT_ID 7o5t5gvjmq6lhpp0ufh9pvcrdr
AWS_ACCOUNT_ID 014155356487

Production:

Variable Value
API_URL / API_BASE_URL https://hhiczft6j0.execute-api.us-east-1.amazonaws.com
USER_POOL_ID us-east-1_kwfKoAcHa
USER_POOL_CLIENT_ID 23047gjjjn7rqnpc46nqm2s247
AWS_ACCOUNT_ID 396662537080

Env File Locations

App Dev Prod
ovrly_photo .env .env.prod
ovrly_draw .env (none)
ovrly_web .env.local (none)
admin .env.local .env.production

Source of Truth

  • ovrly_photo: .env and .env.prod are authoritative for Flutter apps
  • admin: .env.production is authoritative for production admin dashboard
  • All env files now use consistent ovrly-* naming and correct API URLs

CloudWatch Logs

Log Group Naming

There are three log group prefixes (due to stack evolution):

Prefix Status Example
OvrlyApiStack-Dev-* Current OvrlyApiStack-Dev-OvrlyPhotoAuthSigninFunction6A07-*
LinesOfSightDrawingsApiSt-* Legacy (still active) LinesOfSightDrawingsApiSt-GetOverlaysFunction8C26B-*
OvrlyIntegration-dev-* Integration functions OvrlyIntegration-dev-TriggerModalWebhook

Finding Log Groups

# List all log groups
aws logs describe-log-groups --profile los-dev \
  --query 'logGroups[*].logGroupName' --output text | tr '\t' '\n'

# Find log groups by keyword (e.g., signin, photos, overlays)
aws logs describe-log-groups --profile los-dev \
  --query 'logGroups[*].logGroupName' --output text | tr '\t' '\n' | grep -i signin

# Common searches:
grep -i signin      # Auth signin functions
grep -i signup      # Auth signup functions
grep -i passkey     # WebAuthn/passkey functions
grep -i photos      # Photo CRUD functions
grep -i overlays    # Overlay CRUD functions
grep -i pipeline    # AI pipeline functions

Querying Logs

Get recent logs (last hour):

LOG_GROUP="/aws/lambda/OvrlyApiStack-Dev-OvrlyPhotoAuthSigninFunction6A07-jfvCl2pstUUB"

aws logs filter-log-events \
  --profile los-dev \
  --log-group-name "$LOG_GROUP" \
  --start-time $(($(date +%s) * 1000 - 3600000)) \
  --limit 50 \
  --query 'events[*].message' \
  --output text

Search for errors (last 24 hours):

aws logs filter-log-events \
  --profile los-dev \
  --log-group-name "$LOG_GROUP" \
  --filter-pattern "ERROR" \
  --start-time $(($(date +%s) * 1000 - 86400000)) \
  --limit 20 \
  --query 'events[*].message' \
  --output text

Search for specific text:

aws logs filter-log-events \
  --profile los-dev \
  --log-group-name "$LOG_GROUP" \
  --filter-pattern "user@example.com" \
  --start-time $(($(date +%s) * 1000 - 86400000)) \
  --query 'events[*].message' \
  --output text

Live tail (streaming - max 3 hours):

aws logs start-live-tail \
  --profile los-dev \
  --log-group-identifiers "arn:aws:logs:us-east-1:014155356487:log-group:$LOG_GROUP"

Time Calculations

CloudWatch uses milliseconds since epoch:

  • Last hour: $(($(date +%s) * 1000 - 3600000))
  • Last 24 hours: $(($(date +%s) * 1000 - 86400000))
  • Last 7 days: $(($(date +%s) * 1000 - 604800000))

Common Log Group Names (Dev)

Auth (Photo app):

  • OvrlyApiStack-Dev-OvrlyPhotoAuthSigninFunction* - Email/password signin
  • OvrlyApiStack-Dev-OvrlyPhotoAuthSignupFunction* - User registration
  • OvrlyApiStack-Dev-OvrlyPhotoAuthGoogleSigninFuncti* - Google OAuth
  • OvrlyApiStack-Dev-OvrlyPhotoAuthAppleSigninFunctio* - Apple signin
  • OvrlyApiStack-Dev-OvrlyPhotoAuthPasskey* - Passkey/WebAuthn

Domain functions:

  • OvrlyApiStack-Dev-PhotosCreateFunction* - Create photo
  • OvrlyApiStack-Dev-OverlaysListFunction* - List overlays
  • OvrlyApiStack-Dev-OverlaysGetFunction* - Get single overlay

What NOT to Do

  • NO aws logs tail - Does not exist in AWS CLI v2
  • NO --follow - Use start-live-tail instead for streaming
  • NO guessing log group names - Always query describe-log-groups first