Pixelated Empathy
Pioneering the digital frontier of mental health.
The Vision
Pixelated Empathy is fundamentally reshaping the mental health landscape.
Historically, the clinical world has pushed back against integrating deeply with
the digital realm—often out of valid concerns for safety, empathy, and privacy.
We are here to bridge that gap in a highly positive and beneficial way. By
merging clinical rigor with advanced, carefully aligned AI, we create
environments where high-stakes, human-centered teams can practice, analyze, and
evolve their emotional intelligence before stepping into real-world scenarios.
Our goal moving forward is to scale deep, genuine empathy through digital
platforms without losing the profoundly human essence of care. We believe that
by thoughtfully bringing therapeutic principles into the digital realm, we can
unlock new paradigms for training, healing, and connection.
Quick Start
Prerequisites
| Requirement | Version | Check |
|---|
| Node.js | >= 24 | node --version |
| pnpm | 12.16.1 | pnpm --version |
| Python | 3.14 | python3 --version |
| uv | latest | uv --version |
| PostgreSQL | 17+ | psql --version |
| Redis | 7+ | redis-cli --version |
| Docker | latest | docker --version |
Setup
# 1. Clone with submodules (or init them after cloning)
git clone --recursive https://github.com/daggerstuff/pixelated.git
cd pixelated
# If already cloned without --recursive:
git submodule update --init --recursive
# 2. Install dependencies
pnpm install
# 3. Start the dev server
pnpm dev
The app runs at http://localhost:5173.
Submodule Note: This repo uses three git submodules (ai/, foresight/,
docs/). After any clone or pull, run
git submodule update --init --recursive to sync them. Without this step,
those directories will be empty.
All Services
To run the full stack (web + AI services + bias detection + analytics + worker):
pnpm dev:all-services
See CONTRIBUTING.md for the complete developer guide.
The Ecosystem
This platform operates as a cohesive unit across four primary repositories.
Together, they form the secure, intelligent backbone of our clinical AI engine:
| Repository | Role |
|---|
| pixelated (Main Core) | Primary orchestrator: application surfaces, clinical dashboards, API routes, shared product logic. |
| ai (Cognitive Engine) | Model research and training: inference, emotional signal analysis, clinical validity pipelines. |
| foresight (Continuity & Memory) | Persistent contextual memory for AI agents across longitudinal therapeutic simulations. |
| docs (Knowledge Base) | HIPAA compliance, security posture, clinical feedback loops, architecture decisions. |
ai/, foresight/, and docs/ are git submodules — run
git submodule update --init --recursive after cloning to populate them.
Project Structure
pixelated/
├── apps/
│ ├── web/ # Main Astro 6 + React 19 application
│ └── business-strategy-cms/ # Business strategy CMS
├── ai/ # Submodule: AI inference & training (Python)
├── foresight/ # Submodule: Foresight MCP memory server (Python)
├── docs/ # Submodule: Documentation knowledge base
├── agents/ # AI agent packages (advisor, content, eve, intake, pipeline)
├── packages/ # Shared workspace packages
├── config/ # Vitest, Playwright, and other configs
├── content/ # Astro content collections
├── data/ # Seed data and fixtures
├── infra/ # Infrastructure (Docker, K8s)
├── scripts/ # DevOps and utility scripts
└── tests/ # Integration and E2E tests
Development
Common Commands
pnpm dev # Start dev server (port 5173)
pnpm dev:all-services # Start all services concurrently
pnpm build # Production build
pnpm lint # Lint (oxlint, type-aware)
pnpm format # Format code (oxfmt + prettier)
pnpm test:unit # Unit tests (Vitest)
pnpm test:integration # Integration tests
pnpm e2e # End-to-end tests (Playwright)
pnpm e2e:ui # Interactive E2E
Python (ai/ and foresight/ submodules)
uv run pytest # Run Python tests
uv run ruff check . # Lint Python
uv run ruff format . # Format Python
The ai/ Training Submodule
ai/ is the Python training and research engine (Python 3.14, managed with
uv). It is not part of the root uv workspace — it ships its own
pyproject.toml and uv.lock:
cd ai
uv sync # Create the submodule venv
uv run pytest # Full test suite
make test # Training test suite (matches CI)
uv run ruff check . # Lint
Training datasets are versioned with DVC (remote: Cloudflare R2,
pixel-archive/ai-data); fetch them with cd ai && dvc pull.
CI gate: the Quality workflow's ai submodule strict ratchet job
(scripts/ci/ai-strict-ratchet.mjs) pins the submodule's legacy
strict-typing debt per file and per error code in
scripts/ci/ai-strict-baseline.json. It fails when that debt grows or a new
.py file fails mypy --strict — new code must be strict-clean, and debt
reductions are re-pinned with --update / --prune.
Submodule Management
git submodule update --init --recursive # Init after fresh clone
pnpm submodules:sync # Re-sync after pull
Tech Stack
| Layer | Technology |
|---|
| Frontend / SSR | Astro 6 + React 19 (TypeScript, Tailwind CSS) |
| Backend / AI | FastAPI / Express / Flask (Python 3.14 via uv) |
| Database | PostgreSQL 17 + pgvector |
| Caching | Redis |
| State | Zustand |
| Package Manager | pnpm 12.16.1 |
| Runtime | Node.js >= 24 |
Contributing
See CONTRIBUTING.md for branch naming, commit conventions,
testing, and security rules.
Key Rules
- No error suppression: Never use
@ts-ignore, @ts-nocheck, # noqa, or
# type: ignore
- No credentials in code: Never commit API keys, passwords, or patient data
- Lint before push: Run
pnpm lint and pnpm format:check before pushing
- AI assistants: See
AGENTS.md for AI coding assistant conventions
Documentation
The docs/ submodule contains 980 files across 28 subdirectories. See
DOCS.md for a full index of all subdirectories, or browse the key
areas below:
Run git submodule update --init --recursive first if docs/ is empty.
Security
Report vulnerabilities to
[email protected].
See docs/SECURITY.md and
docs/THREAT_MODEL.md for details.
© 2026 Pixelated Empathy. All rights reserved.
