🛠️ MoT Software Overview (Developer)

This document explains how MoT is organized, how authentication and user scoping work, and where to extend behavior safely.

If you are onboarding, read this once front-to-back, then keep it open while navigating the codebase.

Table of Contents

1. System at a Glance
2. Architecture
3. Repository Map
4. Authentication and Identity
5. Data Scoping and Persistence
6. Capture and Template Pipelines
7. Rules Engine
8. Deep Linking (iOS Shortcuts)
9. Storage Backends
10. Testing and Validation
11. CI/CD and Infrastructure
12. Extension Playbook
13. Operational Pitfalls
14. Related Docs

System at a Glance

MoT has three primary surfaces:

• Backend API (src/): source of truth for auth, Notion integration, capture/commit flows, rules, summaries, and backups.
• Web console (web/index.html): lightweight, static, operator-focused interface.
• Mobile app (mobile/): Expo/React Native client for day-to-day capture and template usage.

At runtime, both web and mobile call the same backend domain logic. The backend then orchestrates Notion + local persistence.

Architecture

Core topology

[Web UI] ----\
              \            +-------------------+
[Mobile App] -----> HTTP ->| MoT Backend (TS) |-----> [Notion API]
                           +-------------------+
                                     |
                                     v
                          [File Storage (data/) or DB]

Runtime modes

• Local/dev mode: backend + static local web + file-backed storage.
• Production mode: AWS ALB/Cognito front door + ECS service + production API domain.

Design characteristics

• API-first backend with shared behavior across clients.
• Explicit user scoping via userId to isolate data and tokens.
• Controlled write surface via allowlisted Notion databases.

Repository Map

Authentication and Identity

MoT uses layered auth; exact behavior differs by entrypoint.

Production web (motapps.com + api.motapps.com)

1. AWS ALB + Cognito + Google OAuth authenticates browser sessions.
2. Backend may additionally require:

• APP_ACCESS_TOKEN bearer token
• ALLOWED_USER_EMAILS allowlist

1. Backend reads OIDC identity from ALB-injected headers and exposes session data at:

• GET /auth/session

Mobile (/mobile/* style usage)

Mobile traffic is built to work even when ALB OIDC headers are not present.

• Uses Authorization: Bearer <APP_ACCESS_TOKEN> when configured.
• Sends explicit userId chosen in mobile settings.
• If ALLOWED_USER_EMAILS is active, backend constrains valid mobile userId values.

Notion OAuth

• Always stored per userId.
• Can be encrypted at rest when MOT_DATA_ENCRYPTION_KEY is configured.

Identity bugs are usually userId consistency bugs—not Notion bugs.

Data Scoping and Persistence

Most durable state is keyed by userId:

• Notion OAuth credentials
• Allowlist entries
• Cached schema metadata
• Capture and summary rules
• Template definitions
• Backup cursors
• Audit artifacts

Why this matters

• Web and mobile can appear “out of sync” if they use different userId values.
• Rotating userId in testing can produce ghost states that look like missing data.

Debug checklist for missing data

1. Confirm current userId in client settings/session payload.
2. Confirm Notion OAuth exists for that same userId.
3. Confirm allowlist and schema cache are populated under that userId.

Capture and Template Pipelines

MoT supports two primary commit styles.

1) Deterministic template commits

Best for predictable, repeated workflows.

• Source: template schema + defaults + required directives
• Output: stable Notion property mapping
• Used by: form entry and template-scoped voice entry

2) AI-assisted capture commits

Best for freeform notes and quick thoughts.

• Source: text or voice transcript
• Processing: propose ➜ optional follow-up ➜ commit
• Constraints: allowlist + schema + rules + optional template context

Important endpoints

• GET /shortcuts/templates
• POST /shortcuts/templates/upsert
• POST /shortcuts/templates/install-logging-core
• POST /capture/propose
• POST /capture/commit
• POST /notion/pages/update (post-commit edits)

Template-to-capture bridge

Templates can also be referenced by capture through generated shortcut ids:

• mot-tmpl-<templateId>

This allows voice flows to inherit template constraints without duplicating config.

Rules Engine

Rules are applied in layered precedence:

1. Global defaults
2. Per-table capture rules
3. Per-table summary rules (summary path)

Typical rule concerns

• Date column preference and fallback behavior
• Include-time toggles and default-time assumptions
• Prompt hints for extraction/formatting bias
• Property-level directives

Code touchpoints

• Mobile UI: mobile/src/screens/RulesScreen.tsx
• Web UI: rules panel in web/index.html

Deep Linking (iOS Shortcuts)

MoT supports deep links to launch directly into:

• Template form mode
• Voice capture mode with template shortcut context

Link variants

• Expo Go links: require active dev server.
• Custom scheme app links (mot://...): intended for installed builds.

Implementation area

• mobile/src/shortcuts/ handles deep link parsing and navigation wiring.

Storage Backends

Default storage is file-backed under data/ (gitignored), optimized for local and single-instance environments.

For a deeper dive, read Storage Architecture.

Production caution

File storage is risky in multi-instance deployments unless you provide:

• shared durable volume semantics,
• consistency controls, and
• robust locking/serialization.

If scaling horizontally, move toward a transactional shared datastore.

Testing and Validation

Standard commands

• Backend tests: npm test
• Mobile tests: npm --prefix mobile test
• Mobile type checks: npm --prefix mobile run typecheck

Suggested developer rhythm

1. Run focused backend tests after logic changes.
2. Run mobile typecheck for any API contract / screen changes.
3. Validate end-to-end flows against a known userId and allowlist.

CI/CD and Infrastructure

Terraform drift note

Once CI/CD owns task definition rollouts, avoid having Terraform continuously rewrite ECS service task definition revisions. Otherwise, deployments can fight each other (“tug-of-war”).

Extension Playbook

Use this section when adding features.

Add a new API route

1. Implement handler in src/api/handlers.ts.
2. Register route in src/api/server.ts.
3. Add client call:

• web: relevant API client module
• mobile: mobile/src/api/motApi.ts

1. Add/update tests for handler + route behavior.

Add a new template field type

1. Extend schema parsing in src/notion/schema.ts.
2. Update template renderer paths (web + mobile).
3. Ensure mapping to Notion property payload is deterministic.
4. Add tests covering field parse, form handling, and commit mapping.

Add a new rules capability

1. Define precedence behavior (global vs table-level).
2. Update storage model and API surface.
3. Expose controls in mobile/web UIs.
4. Add tests for conflict resolution and fallback logic.

Operational Pitfalls

• Mismatched userId creates most “data vanished” reports.
• Unshared Notion databases cause 404/permission-style errors.
• Stale schema cache causes property mapping surprises after Notion schema edits.
• Overly broad global rules can degrade extraction quality across unrelated tables.

Related Docs

• User guide: Guidebook
• Storage details: Storage Architecture
• Ops visibility: Operational Dashboards & Alerts
• AWS planning notes: AWS Deployment Plan