MATAN AI
Ring sees the event. Matan AI understands the situation, decides what deserves attention, and tells you.
Matan means “eye” in Tetum, the language of Timor-Leste.
Ring's own app can already tell a person from a parcel. Through the Ring Partner API, though, a developer gets a device, a history entry and a camera frame — the understanding is yours to build. MATAN AI builds it: every Ring event is read by Amazon Nova Pro, scored by a deterministic Decision Engine, checked against Smart Rules you control, and only then — if it deserves your attention — turned into one clear email that says what was seen and which rule decided to send it.
Built for the Build, Ship, Shape: Amazon Developer Hackathon (Ring track + AWS Builder mini challenge) against the real Ring Developer Playground, running on AWS.
What it does
| 🧠 Understands, not just detects | Nova Pro reads the snapshot (and the clip when it helps) and returns a summary, category, confidence, observations and what it is unsure about. |
| ⚖️ Decides, and explains why | A deterministic Decision Engine turns the reading into a priority and an action; your Smart Rules have the last word. Every decision stores its reason. |
| 🔕 Stays quiet on purpose | Most events end as Ignore or Monitor. Email is reserved for Notify and Escalate — with quiet hours, sensitivity and repeat detection you control. |
| 💬 Answers questions about your home | The assistant is grounded in your own devices, events, decisions and rules — never invented. |
| 📺 Real Ring integration | WebRTC live view, on-demand snapshots, event history, device capabilities — all from the Ring API. |
| 🤝 Honest by design | Anything the Ring API or this build cannot do is labelled future integration in the UI instead of being faked. |
See it
| Live demo | https://main.d3q4rxuohabv2i.amplifyapp.com |
| Documentation (in-app) | /docs — architecture, integrations and every page audited |
| Demo Mode | Sign in and choose Demo Mode to explore with sample data, no Ring account needed |
| Real Mode | Paste a 30-minute Ring Developer Playground token and the whole app runs on real Ring data |
Architecture at a glance
| Diagram | What it answers |
|---|---|
| System architecture | How the browser, the Next.js server, AWS and Ring fit together |
| Event → alert lifecycle | What happens in the 2.7 seconds after Ring records something |
| Feature map | What powers each page, and what is a future integration |
| Deployment & security | How it ships to AWS and what it refuses to do with your data |
Stack: Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · Amazon Cognito · Amazon Bedrock (Nova Pro) · Amazon DynamoDB · Amazon S3 · Amazon SES · AWS Amplify Hosting · Ring API (Developer Playground).
Run it yourself
bashgit clone https://github.com/ajitonelsonn/matan-ai.git
cd matan-ai
pnpm install
cp .env.example .env # fill in the values below
pnpm cognito:provision # user pool + app client
pnpm dynamodb:check # table MatanAI (PK/SK)
pnpm s3:provision # private media bucket
pnpm dev # http://localhost:3000
Full instructions — AWS resources, IAM policy, Google sign-in, SES verification and deploying to Amplify — are in docs/SETUP.md and docs/AWS_DEPLOYMENT.md.
Demo Mode works with nothing but Cognito configured, so you can see the whole product before wiring any Ring or AI service.
Documentation
Everything is in docs/ and is also browsable inside the app at /docs:
- Architecture — the four diagrams above, with the flows written out
- Real Mode page audit — every page: what is real, what is a future integration, and how it was verified
- Developer feedback — friction log and feature requests for the Ring and AWS teams
- Implementation notes — Bedrock/Nova · Cognito auth · DynamoDB · S3 media · SES notifications · Care Context & Smart Rules · Ring device intelligence · AWS deployment
Project principles
- Nothing is simulated in Real Mode. A panel is backed by Ring, AWS or Matan's own stored data — or it is labelled a future integration.
- Per-user by construction. Every stored item is keyed by the verified Cognito
sub; one user's query can only read their own data. - Secrets stay server-side. The Ring token lives in a sealed HttpOnly cookie, AWS access goes through an IAM role, and the media bucket is private.
- Explainable decisions. Model observations, engine reasons and the matched rule are stored with every event.
Built in Timor-Leste 🇹🇱
Made in Dili for Safer Homes, Stronger Communities. The product is designed for places where a neighbour, a grandparent or a small shop owner needs to know what matters — without wading through a hundred motion alerts.
License
MIT — you are free to run, modify and deploy your own instance.
Ring, AWS, Amazon Bedrock, Amazon Nova and other product names are trademarks of their respective owners. This project is not affiliated with or endorsed by them.