Lifelyn API

Wallet-authorized patient memory, fail-closed by default.

📖 Documentation

NestJS/Fastify is the sole authorization and system-of-record boundary for Lifelyn. Freighter wallet challenge signing is the only login mechanism — provider verification and passkey MFA add clinical privileges on top, they are never an alternative login. Every protected route fails closed (returns an explicit error) rather than falling back to fixture or synthetic data when PostgreSQL, Redis, private object storage, the malware scanner, the AI service, or the Stellar signer is unavailable.

Table of contents

• Maintainers
• What's implemented
• Architecture
• Quick start
• Environment variables
• Testing
• Contributing
• Contributors

Maintainers

	Name	Role	Contact
🧑‍💻	Chijioke	Maintainer	@precious1joe on Telegram · @Cjay-Cyber-2 on GitHub

What's implemented

Wallet identity and profile resolution, passkey MFA, provider verification callbacks, encrypted record upload/finalization/source access, ingestion and reindex queues, normalized timeline review and trends, evidence-only conversations ("Ask History"), scoped consent with immediate revocation, append-only access audit, integrity verification, and conservative FHIR R4 import/export. OpenAPI is served at /openapi; liveness at /v1/health.

Architecture

Freighter wallet ──sign challenge──▶ Lifelyn API (this repo)
                                             │
                       ┌─────────────────────┼─────────────────────┐
                       ▼                     ▼                     ▼
                  PostgreSQL           Redis (BullMQ)        Object storage
                  (Prisma)             ingestion/reindex     (private, S3-compatible)
                       │                     │
                       ▼                     ▼
                  Lifelyn AI          Stellar signer service
              (evidence extraction,   (opaque refs/hashes only —
               citation-verified       never readable medical
               answers)                 content on-chain)

Every new endpoint carries Zod validation, an authorization check, safe error responses, OpenAPI docs, and an audit-event write where relevant — see CONTRIBUTING.md.

Quick start

pnpm install --frozen-lockfile
cp .env.example .env   # fill every blank secret/service value
docker compose -f docker-compose.dev.yml up -d --wait   # Postgres/pgvector, Redis, private MinIO bucket
pnpm db:generate && pnpm db:deploy
pnpm dev            # HTTP service
pnpm dev:worker      # background workers, separate terminal
pnpm dev:signer      # Stellar signing service (needs the SIGNER_* and contract variables), separate terminal

Environment variables

See .env.example for the full list. Notable constraints:

• AI_SERVICE_JWT_SECRET must exactly match the AI service's SERVICE_JWT_SECRET.
• Production must set KMS_PROVIDER=external and put signing/encryption material in a real secret manager — local development uses a built-in AES-GCM wrapper instead.
• Malware scanning is mandatory and fails closed. Set MALWARE_SCANNER_PROVIDER=clamd with CLAMD_HOST to scan with a ClamAV daemon (docker compose -f docker-compose.dev.yml --profile clamav up -d clamav), or leave it unset and point MALWARE_SCANNER_URL at an HTTPS scanning service. Any scanner error, timeout or unreachable daemon rejects the upload. Configure clamd StreamMaxLength to at least 32M.
• STELLAR_SIGNER_SERVICE_URL points at the private signing service in src/signer/ (pnpm start:signer). This API never accepts or stores a raw Stellar seed. See docs/SIGNER.md for its security model, configuration and Testnet verification.

Testing

pnpm exec prisma validate && pnpm typecheck && pnpm lint && pnpm test && pnpm build

CI additionally runs the real PostgreSQL integration suite. Public deployment further requires the cross-service integration suite, a backup/restore exercise, and an independent contract/security review — see the workspace-level PRD_TRACEABILITY.md and BUILD_STATUS.md.

Contributing

See CONTRIBUTING.md. Found a security issue? See SECURITY.md instead of opening a public issue.

Contributors