alva/README.md

NeuroSemantics AI

A minimalist mobile app for iOS and Android. The product is one thing only: an intelligent conversation partner with a specialized knowledge base in neurosemantics and NLP. No course portal, no CRM, no community.

Design language: calm, simple, clear. Off-white background, near-black text, one dark blue-green accent. No animations, no gradients.

System overview

apps/mobile      Expo / React Native app (three views: Welcome, Chat, Paywall)
services/api     One Lambda backend (chat, usage, subscription verification)
infra            AWS CDK stack (the entire cloud environment)
db/migrations    SQL schema (two tables: users, usage)

A new developer should understand the whole system in under an hour. Every piece exists for a reason; if a feature does not make the core product better, it is not built.

Request flow

1. The app signs in via the Cognito hosted UI (Apple / Google / email) and receives a JWT.
2. POST /chat goes through API Gateway (JWT authorizer) to the single Lambda.
3. The Lambda checks the free-tier quota in PostgreSQL (Aurora Serverless v2). Over the limit and not subscribed → HTTP 402 → the app shows the paywall.
4. Otherwise it calls the OpenAI Responses API with the Markdown knowledge base (services/api/knowledge/) as system instructions and returns the reply.

Conversations are never stored server-side; the client holds them in memory and sends the running transcript with each request. The database stores the absolute minimum: users (id, email, provider, subscription_status, created_at) and usage (messages_used, last_reset). No profiling, no training on user data. Error logging is anonymized (no message content).

Payments

Subscription logic is shared (services/api/src/subscription/); the payment provider differs per platform behind one PaymentProvider interface:

• iOS — In-App Purchase; the backend verifies the app receipt with Apple.
• Android — Google Play Billing; the backend verifies the purchase token with the Play Developer API.
• Web (future) — a Stripe adapter slots into the same interface.

Plans: Monthly and Yearly. Nothing else.

Free tier: FREE_MESSAGE_LIMIT messages (default 50 ≈ 5–10 conversations), resetting every USAGE_RESET_DAYS days.

Getting started

npm install            # installs all workspaces
npm run lint
npm run typecheck
npm test

Mobile app

cd apps/mobile
npm start              # Expo dev server

Fill in extra in app.json (API URL, Cognito domain and client id) from the CDK stack outputs. In-app purchases require a development build (expo run:ios / expo run:android), not Expo Go.

Backend + infrastructure

cd infra
npx cdk deploy

After the first deploy:

1. Put values into the neurosemantics/app secret in Secrets Manager: OPENAI_API_KEY, APPLE_SHARED_SECRET, GOOGLE_SERVICE_ACCOUNT_JSON.
2. Run db/migrations/001_init.sql against the cluster (credentials are in the RDS-managed secret).
3. Optional: enable Apple/Google sign-in by passing CDK context (googleClientId, googleClientSecret, appleTeamId, appleKeyId, applePrivateKeySecretName). Email sign-in works out of the box.

CI/CD

GitHub Actions: ci.yml lints, type-checks and tests every PR; deploy.yml deploys the CDK stack on every push to main (set the AWS_DEPLOY_ROLE_ARN secret for OIDC). Store builds ship via EAS (eas build) when you choose to release.

Security

• All traffic over HTTPS; every API route requires a Cognito JWT.
• Secrets live in AWS Secrets Manager only — no API keys in the client.
• The Lambda runs in private subnets; the database is not publicly reachable.

Product philosophy

Every new feature must justify itself. The allowed AWS surface is API Gateway, Lambda, Cognito, S3, Secrets Manager and CloudWatch — and V1 does not even need S3. No Redis, no Kubernetes, no Kafka, no Elasticsearch, no queues, no microservices. One backend. Maximal simplicity.