Everything about how MATAN AI works
Ring sees the event. Matan AI understands the situation, decides what deserves attention, and tells you. These pages are the project's own documentation — architecture diagrams, the Ring and AWS integrations, and an honest audit of every page in Real Mode, including what is still a future integration.
Built on real servicesRing API, Cognito, Bedrock, DynamoDB, S3 and SES — no mock data in Real Mode.
Audited page by pageEach page documents what is live, what is a future integration, and how it was verified.
Yours to runMIT licensed, with provisioning scripts and a Demo Mode that needs no Ring account.Start here
MATAN AI — overviewRing sees the event. Matan AI understands the situation, decides what deserves attention, and tells you.Read →Run MATAN AI yourselfEverything here is reproducible with your own AWS account and a free Ring Developer Playground session. Demo Mode needs only Cognito, so you can see the whole product before wiring any AI orRead →
Architecture
The product, page by page
Real Mode page auditOne document per page, each with: what the page does in Real Mode (signed-in user, Ring Developer Playground, AWS), a Mermaid diagram of how it works, a table of every section/function with Read →Sign in, Sign up & Mode chooserRoutes: /login, /register, /verify-email, /forgot-password, /auth/callback (Google) · Components: components/auth/ (AuthLayout, LoginForm, SignUpForm, VerifyEmailForm, ForgotPasswordForm, GoRead →Home — Real ModeRoute: / · Component: components/pages/HomeDashboard.tsx · Data: GET /api/ring/overview (Real Mode) via AppDataProviderRead →Live View — Real ModeRoute: /live · Component: components/pages/LivePage.tsx · Ring pieces: components/devices/ring-live-player.tsx, components/devices/ring-live-tools.tsxRead →Events — Real ModeRoute: /events (deep link /events/{id}) · Component: components/pages/EventsPage.tsx · Detail: components/matan/EventDetail.tsx (Ring branch) + components/matan/MatanAnalysisPanel.tsx · DataRead →AI Insights — Real ModeRoute: /insights · Component: components/pages/InsightsPage.tsx · Data: GET /api/ring/overview/insights?range=…&from=…&to=… → buildRingInsights (lib/ring/overview.ts) · Summary: POST /api/maRead →AI Assistant — Real ModeRoute: /assistant · Component: components/pages/AssistantPage.tsx · API: GET/POST/DELETE /api/assistant?mode=ring · Answering: lib/ring/assistant.ts (answerRing) + lib/matan/assistant-contexRead →Automations — Real ModeRoute: /automations · Component: components/automations/ring-automations-view.tsx (Real Mode; components/pages/AutomationsPage.tsx keeps the Demo view) · Data: GET/POST/PATCH/DELETE /api/matRead →Security Modes — Real ModeRoute: /security-modes · Component: components/pages/SecurityModesPage.tsx · API: GET/PATCH /api/security-modes?mode=ring → lib/matan/security-modes.ts · Storage: per-user settings item (USERead →Devices — Real ModeRoute: /devices (detail drawer /devices/{id}) · Components: components/pages/DevicesPage.tsx → components/devices/ring-devices-view.tsx, ring-connected-device-card.tsx, ring-intelligence.tsxRead →Care & Family — Real ModeRoute: /care · Components: components/pages/CarePage.tsx → components/experience/real-mode-care.tsx (Real Mode) + components/care/CareRulesPanel.tsx · APIs: GET/PUT /api/matan/care, GET /apiRead →Business — Real ModeRoute: /business · Components: components/pages/BusinessPage.tsx → components/experience/real-mode-business.tsx (Real Mode) · APIs: GET /api/ring/events?range=7d, POST /api/matan/insights/suRead →Settings — Real ModeRoute: /settings?tab=general|notifications|care|privacy|ai|appearance|region|about · Component: components/pages/SettingsPage.tsx (+ components/care/CareRulesPanel.tsx, components/experienceRead →
Implementation notes
Amazon Cognito Authentication — Implementation NotesMatan AI requires a signed-in user before any dashboard page, Demo/Real mode data, Ring session or Bedrock analysis is loaded. Authentication is handled by Amazon Cognito User Pools through Read →AWS Amplify deployment — runtime notes and production fixesMATAN AI runs on AWS Amplify Hosting (Next.js SSR compute) with a compute role for AWS access (no long-lived keys). Two production symptoms appeared after the first deployment; both had the Read →Care Context & Smart Rules — Implementation ReportMatan AI now interprets real Ring events through a user-configurable care context and a deterministic smart-rule engine layered on top of the existing pipeline. Nova Pro still only interpretRead →Developer feedback — friction log and feature requestsEverything below happened while building MATAN AI against the Ring Developer Playground / Partner API and AWS during the Build, Ship, Shape: Amazon Developer Hackathon (September–October 202Read →DynamoDB Persistence — Implementation NotesMatan AI's server-side state (Ring events, Matan/Nova analyses, connected Ring devices, user settings) is persisted in the single Amazon DynamoDB table MatanAI (us-east-1, on-demand, PK/SK).Read →Email Notifications (Amazon SES + SMTP fallback) — Implementation NotesMatan AI emails the signed-in user when a Matan analysis finishes and the decision clears the user's chosen alert level. Email is transactional only, sent server-side through Amazon SES v2 (Read →Live Ring Playground Event Experience — Implementation NotesGoal: make the existing real pipeline — Ring Playground → event history sync → auto-analysis → Ring snapshot → Nova Pro → Matan Decision Engine → DynamoDB/S3 → notification — visible as a coRead →MATAN AI — Amazon Bedrock + Nova Pro Event Analysis & Matan Decision: Implementation ReportStatus: Implemented and verified against the live Bedrock endpoint (September 2026).Read →MATAN AI — Demo Mode & Real Mode: Implementation ReportStatus: Implemented (September 2026). Builds on the Ring Add Device integration (docs/RINGADDDEVICEIMPLEMENTATION.md), which was left intact.Read →MATAN AI — Ring Add Device Integration: Implementation ReportStatus: Implemented and verified (September 2026) Scope: Add Device → Ring Playground token → server-side Device Discovery → select/configure → persist → Devices page → token-expiry/reconnecRead →Ring Account & Device Intelligence — Implementation NotesShow the signed-in user real facts about their Ring account and devices — status, capabilities, coarse region, configuration — using only what the Ring API returns, feed that device context Read →S3 Media Storage — Implementation NotesRing snapshot/clip bytes that Matan AI analyzes now live in a private S3 bucket with metadata in DynamoDB, instead of bounded process memory. Media survives restarts, and /api/matan/media/:iRead →Setting up Google Sign-In with Amazon Cognito for Matan AIThis guide walks through connecting Sign in with Google to the Matan AI user pool, end to end: Google Cloud Console → Amazon Cognito → the app's .env. It also lists the exact mistakes we hitRead →