From 5c995c057aaf4fe86c49a9416ec59e2374de0d46 Mon Sep 17 00:00:00 2001 From: Anny Levine <59417116+Nili-L@users.noreply.github.com> Date: Thu, 9 Apr 2026 15:29:42 +0300 Subject: [PATCH 1/5] Add project README replacing Vite boilerplate Covers mission, Six Cs model, features, tech stack, getting started, project structure, and research foundation. Replaces README-vite.md as the repo's primary documentation entry point. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f505871 --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# CALMe -- Calm & Alert + +Offline-first psychological first aid for active crisis situations. CALMe delivers real-time, step-by-step trauma response guidance based on the [Six Cs model](https://scholar.google.com/citations?user=yKV0n3YAAAAJ) by Dr. Moshe Farhi -- a peer-reviewed psychological first aid model developed for active conflict zones. + +Built for the reality that during a rocket attack in Israel, a shelling in Ukraine, or a disaster anywhere else, you can't call a therapist, your phone might not have signal, and emergency services are dealing with physical casualties first. + + + + +## The problem + +In the first minutes after a rocket attack, terror incident, or natural disaster, people experience acute stress that shuts down executive function. Existing mental health tools assume connectivity, require onboarding, and rely on emotional soothing -- which actually suppresses the thinking brain during crisis. + +## How CALMe works + +CALMe uses Dr. Farhi's core insight: **activating people during crisis restores executive function faster than calming them.** The fear response and the thinking brain can't run at full power simultaneously -- give someone a cognitive task and the fear starts to quiet. Research shows this can happen in as little as 90 seconds. + +The app guides users through the Six Cs: + +| C | Purpose | Example | +|---|---------|---------| +| **Commitment** | Counter isolation | "I'm here. I'm not going anywhere." | +| **Cognitive Communication** | Re-engage the thinking brain | "Count the people around you. What floor are you on?" | +| **Challenge** | Transform victim to helper | "Check on the person who looks most stressed." | +| **Control** | Restore personal agency | "Do you want to get them water, or sit with them?" | +| **Continuity** | Provide temporal structure | "The siren started at X. You got to shelter. It's over now." | +| **Compassion** | Woven through every message | "You did that. You helped her. That matters." | + +## Key features + +- **Completely offline** -- works with no network connection after the first download. No API calls, no server dependency. Peer-shareable via local network or USB during infrastructure attacks. +- **Natural language understanding** -- handles fragmented, emotional crisis speech using local NLP (Compromise.js + Sentiment analysis). No rigid questionnaires. +- **Adaptive conversation engine** -- 30+ conversation nodes with skip logic. If a user says "I'm in shelter with 6 people," the bot detects completed steps and jumps ahead. +- **No onboarding during crisis** -- opens directly to "I'm here with you." No onboarding forms during crisis. Activities sidebar hidden until recovery phase. +- **Recovery activities** -- breathing exercises, matching games, digital canvas, stretching routines, Sudoku -- triggered by the conversation engine based on stress level. +- **Multi-language** -- Hebrew, Arabic, and English support via compile-time i18n (Paraglide-JS). +- **Accessibility** -- ARIA-compliant contrast, dyslexia-friendly mode (OpenDyslexic font), screen reader support. +- **Companion mode** -- floating helper bubble for users caring for dependents (children, elderly, injured). + +## Tech stack + +| Layer | Technology | +|-------|-----------| +| Frontend | React 19, TypeScript, Vite 7 | +| UI | Radix UI, Tailwind CSS 4 | +| NLP | Compromise.js, Sentiment | +| Offline | Vite PWA Plugin, Workbox service workers | +| i18n | Paraglide-JS (compile-time) | +| Storage | IndexedDB (local profiles, no server) | +| Hosting | Cloudflare Workers | +| CI/CD | GitHub Actions (build, lint, deploy) | +| Linting | OXLint, OXFmt, Husky + lint-staged | + +## Getting started + +```bash +git clone https://github.com/CALMe25/CALMe.git +cd CALMe +npm install +npm run dev +``` + +Open `http://localhost:5173` in your browser. The app runs entirely locally. + +To build for production: + +```bash +npm run build # Output in dist/ (~50MB with all assets) +npm run preview # Preview the production build locally +``` + +## Project structure + +``` +src/ + activities/ # Breathing, games, canvas, stretching + chat_interface/ # Chat UI components + components/ # Shared UI (Radix-based) + contexts/ # React contexts + conversation/ # Conversation engine, controller, maps + hooks/ # Custom React hooks + nlp/ # Natural language processing + parser/ # Multi-signal text analysis + storage/ # IndexedDB profile persistence + paraglide/ # Compiled i18n output + types/ # TypeScript interfaces +docs/ # Architecture, resources, specs +``` + +## Why this matters + +This is not a wellness app. CALMe is built for the minutes between a siren and an all-clear, when a person is alone in a shelter with their phone and no one to call. The Six Cs model has been field-tested during active conflict in Israel and validated across emergency mental health research globally. + +The design philosophy: **don't sedate, activate.** Transform the user from passive victim to active participant. Restore agency, then stabilize. + +## Research foundation + +- Farchi, M., et al. (2018). "The SIX Cs model for Immediate Cognitive Psychological First Aid." *International Journal of Emergency Mental Health and Human Resilience.* +- Farchi, M., et al. (2025). "Effects of a psychological first aid based on the SIX Cs model on acute stress responses." *Psychological Trauma.* +- Farchi & Shlezinger (2026). "The SIX Cs model integrating empathy: a structured cognitive framework for psychological first aid during acute threat." *Frontiers in Psychology.* +- [ICFR -- International Center for Functional Resilience](https://icfr.co.il) + From fadd131f80534b7c2cc1885cbe75406d8a32569d Mon Sep 17 00:00:00 2001 From: Anny Levine <59417116+Nili-L@users.noreply.github.com> Date: Thu, 9 Apr 2026 15:59:23 +0300 Subject: [PATCH 2/5] Add quick-scan summary, visible demo section, architecture highlights Cherry-picked from alt README review: scannable "Why different" bullets at top, visible demo placeholder, and architecture as its own section above the tech stack table. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f505871..028000a 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,17 @@ Offline-first psychological first aid for active crisis situations. CALMe delive Built for the reality that during a rocket attack in Israel, a shelling in Ukraine, or a disaster anywhere else, you can't call a therapist, your phone might not have signal, and emergency services are dealing with physical casualties first. - - +## Why CALMe is different + +- Works fully offline -- no connectivity required after first download +- No onboarding during crisis -- immediate access +- Designed for cognitive activation, not passive calming +- Built for real-world conflict and disaster scenarios + +## 60-second demo + + +*Coming soon -- watch this space.* ## The problem @@ -37,6 +46,14 @@ The app guides users through the Six Cs: - **Accessibility** -- ARIA-compliant contrast, dyslexia-friendly mode (OpenDyslexic font), screen reader support. - **Companion mode** -- floating helper bubble for users caring for dependents (children, elderly, injured). +## Architecture highlights + +- Offline-first design using service workers and local caching -- no runtime backend dependency +- Fully client-side execution -- all NLP, conversation logic, and storage run in the browser +- Modular conversation engine with state-driven flow (30+ nodes, skip logic, phase transitions) +- NLP layer for interpreting fragmented, emotional input (Compromise.js + Sentiment) +- IndexedDB persistence for session continuity across reloads + ## Tech stack | Layer | Technology | From e96d9c99fd1eca0be48859d7a1a60cd8db0765e0 Mon Sep 17 00:00:00 2001 From: Anny Levine <59417116+Nili-L@users.noreply.github.com> Date: Thu, 9 Apr 2026 16:07:38 +0300 Subject: [PATCH 3/5] Add crisis statistics, MA'ASEH naming, WCAG 2.2, and team section - Problem section: Oct 7 stats (21% anxiety, 1.3% treated) with sources - Six Cs table: Hebrew name MA'ASEH added - Accessibility: upgraded to WCAG 2.2 target, speech-to-text planned - Team section: six members with disciplines listed Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 028000a..69a50b8 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,15 @@ Built for the reality that during a rocket attack in Israel, a shelling in Ukrai ## The problem -In the first minutes after a rocket attack, terror incident, or natural disaster, people experience acute stress that shuts down executive function. Existing mental health tools assume connectivity, require onboarding, and rely on emotional soothing -- which actually suppresses the thinking brain during crisis. +In the first minutes after a rocket attack, terror incident, or natural disaster, people experience acute stress that shuts down executive function. Since October 7, 2023, 21% of Israelis reported moderate-to-severe anxiety symptoms and 38% reported at least one mental health symptom. The State Comptroller found that resilience centers meant to serve an estimated 1.3 million affected people had treated fewer than 15,750 by end of 2023 -- less than 1.3% of those in significant distress. + +Existing mental health tools assume connectivity, require onboarding, and rely on emotional soothing -- which actually suppresses the thinking brain during crisis. ## How CALMe works CALMe uses Dr. Farhi's core insight: **activating people during crisis restores executive function faster than calming them.** The fear response and the thinking brain can't run at full power simultaneously -- give someone a cognitive task and the fear starts to quiet. Research shows this can happen in as little as 90 seconds. -The app guides users through the Six Cs: +The app guides users through the Six Cs (known in Hebrew as MA'ASEH / מעש"ה): | C | Purpose | Example | |---|---------|---------| @@ -43,7 +45,7 @@ The app guides users through the Six Cs: - **No onboarding during crisis** -- opens directly to "I'm here with you." No onboarding forms during crisis. Activities sidebar hidden until recovery phase. - **Recovery activities** -- breathing exercises, matching games, digital canvas, stretching routines, Sudoku -- triggered by the conversation engine based on stress level. - **Multi-language** -- Hebrew, Arabic, and English support via compile-time i18n (Paraglide-JS). -- **Accessibility** -- ARIA-compliant contrast, dyslexia-friendly mode (OpenDyslexic font), screen reader support. +- **Accessibility (WCAG 2.2)** -- ARIA-compliant contrast, dyslexia-friendly mode (OpenDyslexic font), screen reader support, speech-to-text and text-to-speech planned. - **Companion mode** -- floating helper bubble for users caring for dependents (children, elderly, injured). ## Architecture highlights @@ -110,6 +112,17 @@ This is not a wellness app. CALMe is built for the minutes between a siren and a The design philosophy: **don't sedate, activate.** Transform the user from passive victim to active participant. Restore agency, then stabilize. +## Team + +CALMe is built by a multidisciplinary team, not a solo side project: + +- **Ziva Wernick** -- Computer Science, project and information systems management +- **Ro'i Bandel** -- Development +- **Rona Eckert** -- Aerospace engineer, system engineering and integration lead +- **Matan Dahan** -- Social worker, therapeutic content developer and resilience evaluator +- **Anat Levine** -- UX/UI architect, user experience design +- **Josh Levine** -- Technical writer, software architecture, language model integration + ## Research foundation - Farchi, M., et al. (2018). "The SIX Cs model for Immediate Cognitive Psychological First Aid." *International Journal of Emergency Mental Health and Human Resilience.* From 2963ebc720e744fa2130f57fd7856b7e1688bb48 Mon Sep 17 00:00:00 2001 From: Anny Levine <59417116+Nili-L@users.noreply.github.com> Date: Thu, 9 Apr 2026 16:09:21 +0300 Subject: [PATCH 4/5] Add target populations, impact analysis, and roadmap docs - docs/target-populations.md: immigrants, disabilities, caregivers, with accessibility statistics and State Comptroller findings - docs/impact-analysis.md: economic cost (4B NIS), expected impact, global scalability case - docs/ROADMAP.md: structured future milestones (LLM integration, accessibility, platform integration, UI) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/ROADMAP.md | 44 ++++++++++++++++++++++++++++++++++++++ docs/impact-analysis.md | 44 ++++++++++++++++++++++++++++++++++++++ docs/target-populations.md | 33 ++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 docs/ROADMAP.md create mode 100644 docs/impact-analysis.md create mode 100644 docs/target-populations.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..7ad161f --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,44 @@ +# Roadmap + +## Current state + +CALMe has a working conversation engine with 30+ nodes, offline PWA architecture, NLP-based input parsing, and recovery activities. The Six Cs flow is implemented with adaptive skip logic and phase transitions. + +## Next milestones + +### Conversation and content + +- [ ] Complete mapping of flowcharts for all case study scenarios +- [ ] Validate conversation paths with mental health professionals +- [ ] Expand therapeutic content based on field testing feedback + +### Language model integration + +- [ ] Connect conversation engine to language models for routing (not independent AI responses -- the model follows conversation maps defined by mental health professionals) +- [ ] Speech-to-text for voice input during crisis (hands may be shaking, typing may not be viable) +- [ ] Text-to-speech for audio output +- [ ] Hebrew translation layer for user responses +- [ ] Arabic and Russian translation support + +### Accessibility + +- [ ] Full WCAG 2.2 compliance audit and remediation +- [ ] Chat interface optimized for hearing impairment +- [ ] Animated avatar interface for more natural user connection +- [ ] Sign language avatar integration (varies by country -- ISL for Israel, ASL for US, etc.) + +### Platform integration + +- [ ] Connect to Home Front Command (Pikud HaOref) API to trigger crisis mode automatically on siren alert +- [ ] Demonstrate full offline functionality on user devices (no network at all, not just cached) +- [ ] Explore peer-to-peer distribution for scenarios where app stores and websites are unreachable + +### UI and experience + +- [ ] Complete user interface including light/dark mode polish +- [ ] Expand activity library based on user feedback +- [ ] Caregiver-specific flows (parent with child, bystander with injured stranger) + +## Contributing + +If you're a mental health professional, translator, accessibility specialist, or developer interested in contributing, open an issue or reach out to the team. diff --git a/docs/impact-analysis.md b/docs/impact-analysis.md new file mode 100644 index 0000000..af7b941 --- /dev/null +++ b/docs/impact-analysis.md @@ -0,0 +1,44 @@ +# Impact analysis + +## The cost of the current situation + +Mental health consequences of ongoing conflict and crisis have a measurable economic impact in Israel: + +- **4 billion NIS** -- estimated overall impact of mental health on Israel's economy +- **1.4 billion NIS** -- added to the state budget for mental health in 2024 + +These figures reflect not just treatment costs but lost productivity, workforce attrition, long-term disability claims, and the downstream effects of untreated acute stress becoming chronic PTSD. + +*Source: Ministry of Health budget allocations, 2024.* + +## Expected impact + +### Immediate: first aid at scale + +CALMe provides an immediate response via a multilingual, accessible solution that can serve most of the country's residents. Unlike resilience centers (which require physical presence, staffing, and operating hours), CALMe is available on any device, any time, with no network required. + +The app doesn't replace professional intervention. It covers the gap between "something just happened" and "I can reach someone who can help" -- a gap that currently has no systematic solution. + +### Long-term: reducing chronic outcomes + +Early intervention during acute stress significantly reduces the likelihood of developing PTSD and chronic anxiety disorders. The Six Cs / MA'ASEH model is specifically designed to restore executive function in the first 90 seconds of interaction, preventing the acute stress response from consolidating into long-term trauma. + +Fewer acute stress cases escalating to PTSD means: +- Reduced long-term treatment burden on the mental health system +- Maintained workforce productivity +- Lower rates of secondary effects (substance abuse, relationship breakdown, economic instability) + +### Economic stability + +By maintaining worker productivity during and after crisis periods, accessible psychological first aid contributes to economic resilience at a population level. The cost of deploying CALMe (a static PWA with no server infrastructure) is negligible compared to the estimated 4 billion NIS annual impact of untreated mental health consequences. + +## Global scalability + +The CALMe model is not Israel-specific. The Six Cs framework has been validated across emergency mental health research internationally. The app's architecture supports: + +- **Language expansion** -- compile-time i18n (Paraglide-JS) means adding a language is a translation task, not an engineering task +- **Cultural adaptation** -- conversation maps can be modified by mental health professionals without code changes (Mermaid-based flow definitions) +- **Institutional deployment** -- government health ministries, HMOs, NGOs, and international organizations (UNHCR, WHO, Red Cross) can deploy CALMe for their populations +- **Conflict-zone portability** -- offline-first architecture means the app works in exactly the infrastructure conditions that conflict creates + +The same app that serves someone in a shelter in Ashkelon can serve someone in a basement in Kharkiv, a hurricane shelter in Florida, or an earthquake aftermath in Turkey. The crisis is different. The neuroscience is the same. diff --git a/docs/target-populations.md b/docs/target-populations.md new file mode 100644 index 0000000..f3f0b16 --- /dev/null +++ b/docs/target-populations.md @@ -0,0 +1,33 @@ +# Target populations + +CALMe is designed for anyone experiencing acute stress during a crisis -- but it's built with specific attention to populations that existing mental health infrastructure consistently fails. + +## Immigrants and new arrivals + +People who recently immigrated or have low socio-economic status face compounded barriers: language gaps, unfamiliarity with local emergency systems, and limited social networks to fall back on during crisis. In Israel, this includes new olim, asylum seekers, and foreign workers who may not speak Hebrew or Arabic fluently. + +CALMe addresses this through multi-language support (Hebrew, Arabic, English) and a conversation interface that doesn't assume cultural context or system familiarity. + +## People with disabilities + +The mental health system is not built for people with disabilities. The numbers make this clear: + +- **7%** of public psychologists received training adapted to working with people with disabilities +- **40%** of mental health institutions in Israel are not fully accessible (structure, signage, transportation, pre-coordination) +- **60%** of respondents with disabilities reported hesitation to seek mental help due to shame, lack of trust in the system, or previous experience of exclusion + +*Source: Ministry of Health report, "Accessibility of mental health services for people with disabilities," December 2023.* + +CALMe targets WCAG 2.2 compliance with screen reader support, dyslexia-friendly mode (OpenDyslexic font), ARIA-compliant contrast ratios, and planned speech-to-text / text-to-speech integration. The goal is an app that works for the people most likely to be excluded from traditional crisis support. + +## Caregivers + +Sometimes the person in crisis isn't the one holding the phone. A parent with a panicking child in a shelter, someone caring for an elderly relative, a bystander trying to help an injured stranger -- these people need guidance too, but from the position of helper rather than victim. + +CALMe's Companion Mode provides a floating helper bubble with guidance tailored to assisting others, maintaining a single continuous cognitive chain rather than splitting into separate interaction threads. + +## The gap between need and service + +The State Comptroller report (June 2024) found that resilience centers established to serve an estimated 1.3 million emotionally affected Israelis had treated fewer than 15,750 by end of 2023 -- less than 1.3% of those in significant distress. + +CALMe doesn't replace professional mental health care. It fills the gap between the moment of crisis and the moment someone can actually reach a professional -- a gap that, for most people, currently has nothing in it at all. From 50812f712081404a68bb33482ceebaf7444e391a Mon Sep 17 00:00:00 2001 From: Anny Levine <59417116+Nili-L@users.noreply.github.com> Date: Thu, 9 Apr 2026 16:21:53 +0300 Subject: [PATCH 5/5] Consolidate Docs/ into docs/, add contributing guide and templates - Migrate all Docs/ files to docs/ with clean lowercase names - Delete orphaned ProfileIntro.tsx/css and Retired/ deprecated files - Update .oxlintrc.json ignore path from Docs/** to docs/** - Add CONTRIBUTING.md with setup, workflow, and content review policy - Add GitHub issue templates (bug report, feature request) - Add pull request template with offline/a11y/lint checklist Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.md | 27 + .github/ISSUE_TEMPLATE/feature_request.md | 19 + .github/pull_request_template.md | 19 + .oxlintrc.json | 2 +- CONTRIBUTING.md | 52 + Docs/ProfileIntro.css | 0 Docs/ProfileIntro.tsx | 40 - .../deprecated-trauma-response-guide.md | 1248 ----------------- .../depricated-conversation-planner.md | 182 --- .../architecture.md | 0 .../content-specification.md | 0 .../conversation-design-guide.md | 0 {Docs => docs}/ghost-files.md | 0 .../implementation.md | 0 {Docs => docs}/profile-intro-questions.md | 0 .../reference.md | 0 .../terms-and-conditions.md | 0 17 files changed, 118 insertions(+), 1471 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md delete mode 100644 Docs/ProfileIntro.css delete mode 100644 Docs/ProfileIntro.tsx delete mode 100644 Docs/Retired/deprecated-trauma-response-guide.md delete mode 100644 Docs/Retired/depricated-conversation-planner.md rename Docs/CALMe_architecture.md => docs/architecture.md (100%) rename Docs/content_specification_form.md => docs/content-specification.md (100%) rename Docs/conversation-design-guide => docs/conversation-design-guide.md (100%) rename {Docs => docs}/ghost-files.md (100%) rename Docs/CALMe_implementation.md => docs/implementation.md (100%) rename {Docs => docs}/profile-intro-questions.md (100%) rename Docs/calme_complete_reference.md => docs/reference.md (100%) rename Docs/Terms and Conditions.md => docs/terms-and-conditions.md (100%) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..18b2550 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,27 @@ +--- +name: Bug report +about: Report something that isn't working correctly +title: '' +labels: bug +assignees: '' +--- + +**What happened?** +A clear description of the bug. + +**Steps to reproduce** +1. Go to '...' +2. Click on '...' +3. See error + +**Expected behavior** +What should have happened instead. + +**Screenshots** +If applicable, add screenshots. + +**Environment** +- Browser and version: +- Device (desktop/mobile): +- Offline or online: +- Language setting: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..f87a9f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest a new feature or improvement +title: '' +labels: enhancement +assignees: '' +--- + +**What problem does this solve?** +Describe the need or gap this feature addresses. + +**Proposed solution** +How you'd like it to work. + +**Alternatives considered** +Other approaches you've thought about. + +**Additional context** +Anything else -- screenshots, links, related issues. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..4c74123 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## What does this PR do? + +Brief description of the change. + +## Why? + +Context or motivation for the change. + +## How to test + +Steps to verify this works correctly. + +## Checklist + +- [ ] Tested offline (no network) +- [ ] Tested across supported languages (if applicable) +- [ ] Accessibility checked (keyboard nav, screen reader, contrast) +- [ ] No new lint warnings (`npm run lint`) +- [ ] Build passes (`npm run build`) diff --git a/.oxlintrc.json b/.oxlintrc.json index 61e707f..2630ec6 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -219,6 +219,6 @@ "**/ui/breadcrumb.tsx", "**/ui/progress.tsx", "**/ui/resizable.tsx", - "Docs/**" + "docs/**" ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bd17192 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to CALMe + +CALMe is a crisis intervention tool. Contributions here have real impact on people in real distress. We take that seriously, and we appreciate that you do too. + +## Getting set up + +```bash +git clone https://github.com/CALMe25/CALMe.git +cd CALMe +npm install +npm run dev +``` + +The app runs at `http://localhost:5173`. Everything runs locally -- no backend, no API keys, no external services. + +## Development workflow + +1. Create a branch from `main` +2. Make your changes +3. Run `npm run lint` and `npm run build` before committing +4. Open a pull request using the PR template + +Commits are linted on pre-commit via Husky + lint-staged. If the hook fails, fix the issue rather than skipping it. + +## What we need help with + +- **Mental health professionals** -- reviewing and refining conversation flows, validating therapeutic content against the Six Cs model +- **Translators** -- expanding language support (Hebrew, Arabic, English currently; Russian and Amharic are priorities) +- **Accessibility specialists** -- WCAG 2.2 audit, screen reader testing, assistive technology validation +- **Developers** -- see [docs/ROADMAP.md](docs/ROADMAP.md) for current priorities + +## Code style + +- TypeScript throughout -- no `any` unless absolutely necessary +- Linting: OXLint (Rust-based, runs fast) +- Formatting: OXFmt +- UI components: Radix UI + Tailwind CSS +- No external API calls in the conversation flow -- everything runs offline + +## Conversation content + +If you're contributing to conversation maps or therapeutic content, coordinate with the team first. Crisis intervention content is reviewed by a mental health professional before merging. Open an issue to discuss before submitting a PR. + +## Reporting issues + +Use the issue templates: +- **Bug report** -- something isn't working +- **Feature request** -- something that should exist + +## Code of conduct + +Be decent. This project exists to help people in crisis. Bring that same care to how you treat contributors. diff --git a/Docs/ProfileIntro.css b/Docs/ProfileIntro.css deleted file mode 100644 index e69de29..0000000 diff --git a/Docs/ProfileIntro.tsx b/Docs/ProfileIntro.tsx deleted file mode 100644 index fb56611..0000000 --- a/Docs/ProfileIntro.tsx +++ /dev/null @@ -1,40 +0,0 @@ -// src/components/ProfileIntro.tsx -//guided user profile questions to parse information to save -//what should I call you? or what is your name? -//what are your preferred pronouns? -//where is your closest safe space? - stairway, public miklat, private mamad -//what is your preferred language? - hebrew, arabic, english -//what are your accessibility needs? - large text, high contrast, screen reader - -import React from "react"; - -// Assuming UserProfile type is still needed within this component -interface UserProfile { - name: string; - age: number; - primaryConcerns: string[]; - gender: string; - language: "hebrew" | "arabic" | "english"; - accessibilityPreferences: string[]; -} - -// You might want to pass props to ProfileIntro later, but for now, -// let's make it a simple component that renders something. -const ProfileIntro: React.FC = () => { - return ( -
-

Welcome to Profile Setup!

-

This is where the user profile introduction will go.

- {/* You will add your actual profile setup UI here */} -
- ); -}; -console.log("ProfileIntro is rendering!"); -export default ProfileIntro; // This line is crucial! diff --git a/Docs/Retired/deprecated-trauma-response-guide.md b/Docs/Retired/deprecated-trauma-response-guide.md deleted file mode 100644 index d64a541..0000000 --- a/Docs/Retired/deprecated-trauma-response-guide.md +++ /dev/null @@ -1,1248 +0,0 @@ -# **DEPRICATED-** - -This document has been replaced by seperate arcitecture and implimentation documents. - - -# Trauma Response App - Developer Implementation Guide - -**Note on Documentation Links**: All documentation links in this guide were valid as of the guide's creation. Please verify current URLs and version numbers before implementation, especially for: -- TensorFlow.js CDN links (use @latest or check current stable version) -- Android API documentation (may have moved with new Android versions) -- npm package versions - -## Project Goal - -### What We're Building -Build an offline-first mobile app that helps people during traumatic events (terror attacks, bombings, natural disasters) by: -- Assessing their safety status through natural conversation -- Providing immediate stress management activities -- Offering cognitive games for distraction -- Helping process the event afterward - -The app guides users through a structured therapeutic process: -1. Safety confirmation -2. Stress assessment -3. Calming activities (if stressed) -4. Cognitive games (when ready) -5. Event processing (if safe) - -### Critical Requirements -- **Must work completely offline** in shelters/bunkers with no network access -- **Must understand natural language** - not just keywords, but phrases like "I can't stop shaking" -- **Must run on old devices** - Android 5.0+ with 1GB RAM -- **Must respect silent mode** during active danger (no sounds/vibration) -- **Must be shareable** - <110MB total for peer-to-peer transfer in emergencies -- **Must load quickly** - <3 seconds after initial setup -- **Must preserve battery** - minimal background processing - -## Architecture Overview - -### Why This Architecture Matters - -This app is designed for crisis situations where: -- **Every second counts**: Initial setup takes 30 seconds, but thereafter loads in <3 seconds -- **Natural language is critical**: USE-Lite adds 25MB but understands "I can't breathe" means panic, not a medical issue -- **Old devices are common**: In emergencies, people use whatever phone works - we target Android 5.0+ -- **Battery life is critical**: Efficient code and minimal background processing preserve battery -- **Sharing is essential**: At 110MB the app can still be shared via local WiFi in shelters -- **True understanding required**: There's no substitute for semantic understanding in crisis response - -The USE-Lite model is our biggest component, but it's non-negotiable. When someone types "everything is spinning and I can't stop shaking," keywords won't help - we need real language understanding. - -### System Architecture - -```mermaid -graph TB - subgraph "User Interface" - UI[HTML/CSS Interface] - MIC[Microphone] - TXT[Text Input] - end - - subgraph "Core Logic" - STT[Web Speech API / Android STT] - PARSER[USE-Lite Parser ~25MB] - CONV[Conversation Manager] - STATE[JS Object / SharedPrefs] - end - - subgraph "Offline Content" - JSON[Conversation JSONs] - ACTS[Activity Scripts] - VID[Compressed Videos] - end - - MIC --> STT - TXT --> PARSER - STT --> PARSER - PARSER --> CONV - CONV <--> STATE - CONV --> JSON - CONV --> ACTS - CONV --> VID - STATE --> UI -``` - -### Technology Stack - -| Component | Web App (PWA) | Android Native | Why This Choice | -|-----------|--------------|----------------|-----------------| -| **Core** | Vanilla JS | Kotlin | No framework overhead | -| **UI** | Custom CSS (~10KB) | XML layouts | Built-in, no libraries | -| **Speech** | Web Speech API | Android STT | Device built-in, free | -| **Storage** | localStorage + IndexedDB | SharedPreferences | Simple, reliable | -| **Parser** | TensorFlow.js USE-Lite (25MB) | TF Lite USE-Lite (25MB) | Understands natural language | -| **Video** | HTML5 `