AI for Alzheimer's

Early Alzheimer's prediction model.

Comment

Inspiration

What it does

How we built it

Challenges we ran into# SYNAPULS

Unified Alzheimer's Disease Analysis & Digital Twin Platform

SYNAPULS is a high-performance neuro-biometric analysis platform designed for advanced threat detection in neurodegenerative pathologies. It integrates real-time biometrics, genomic risk profiling, MRI imaging analysis, and high-fidelity 3D digital twins into a unified command center for Alzheimer's disease research and patient monitoring.

🎯 Features

Core Capabilities

  • Genomic Analysis: SNP file parsing (TSV/BED), polygenic risk scoring, and AI-powered variant analysis
  • Digital Twin: 3D brain visualization with real-time biometric overlay and lesion mapping
  • Patient Management: Comprehensive patient profiles with history tracking and treatment management
  • Biometric Monitoring: Real-time vital signs tracking with AI-powered anomaly detection
  • Inventory Management: Medical supply chain and inventory tracking
  • AI Integration: Google Gemini-powered medical consultancy and analysis
  • Imaging Analysis: MRI feature extraction and vectorization
  • Session Management: Patient session tracking and data playback

Key Modules

  • Brain3D: WebGL-based volumetric data visualization using Three.js
  • Genomics Engine: SNP analysis and Neuro-Resilience Score calculation
  • Biometrics Service: Real-time vital signs monitoring and analysis
  • Treatment Catalog: Comprehensive treatment and medication management
  • Supplier Network: Medical supplier and inventory tracking

🏗️ Architecture

SYNAPULS operates on a split-stack architecture optimized for rapid deployment and scalability.

┌─────────────────────────────────────────────────────────┐
│                    CLIENT (Frontend)                      │
│  React 19 + Vite + Tailwind CSS v4 + Three.js (R3F)     │
│  Port: 5173 (dev) / 3000 (alt)                          │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTP/REST API
┌──────────────────▼──────────────────────────────────────┐
│                    SERVER (Backend)                       │
│  FastAPI + Python 3.10+ + Pandas + Google Gemini         │
│  Port: 8000                                               │
└──────────────────────────────────────────────────────────┘

Client (Tactical Interface)

  • Role: Operator Dashboard & Visual Analytics
  • Tech Stack:
    • React 19 (RC)
    • Vite 6.0
    • Tailwind CSS v4 (Alpha)
    • Zustand (State Management)
    • Three.js / React-Three-Fiber (3D Visualization)
    • Recharts (Data Visualization)

Server (Intelligence Core)

  • Role: Data Ingestion, Inference & Orchestration
  • Tech Stack:
    • FastAPI (High-performance AsyncIO)
    • Python 3.10+
    • Pandas, NumPy (Data Science)
    • Google Generative AI (Gemini)
    • Python-dotenv (Configuration)

📁 Project Structure

synapuls/
├── client/                 # Frontend application
│   ├── src/
│   │   ├── components/     # React components
│   │   │   ├── Brain3D.tsx
│   │   │   ├── DigitalTwin.tsx
│   │   │   ├── GenomicsUpload.tsx
│   │   │   ├── PatientWorkspace.tsx
│   │   │   └── ...
│   │   ├── hooks/          # Custom React hooks
│   │   ├── services/       # API service layer
│   │   ├── store/          # Zustand state management
│   │   └── assets/         # Static resources
│   ├── public/             # Public assets
│   └── package.json
│
├── server/                 # Backend API
│   ├── app/
│   │   ├── api/            # API route handlers
│   │   │   ├── brain.py
│   │   │   ├── genomics.py
│   │   │   └── sensors.py
│   │   └── services/       # Business logic services
│   │       ├── genomics.py
│   │       ├── gemini.py
│   │       └── biometrics.py
│   ├── routers/            # FastAPI routers
│   │   ├── genomics.py
│   │   ├── patients.py
│   │   ├── treatments.py
│   │   ├── inventory.py
│   │   └── ...
│   ├── data/               # JSON data stores
│   ├── main.py             # FastAPI application entry
│   └── requirements.txt
│
├── docs/                   # Documentation
│   ├── protocols/          # Operational procedures
│   └── archive/            # Legacy documentation
│
└── README.md               # This file

🚀 Getting Started

Prerequisites

  • Node.js: v20+ (Download)
  • Python: 3.10+ (Download)
  • npm or yarn: Package manager
  • pip: Python package manager

Installation

1. Clone the Repository

git clone <repository-url>
cd synapuls

2. Backend Setup

cd server

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Frontend Setup

cd client

# Install dependencies
npm install

4. Environment Configuration

Create a .env file in the server directory (optional, for AI features):

GOOGLE_API_KEY=your_gemini_api_key_here

Note: The application will run without GOOGLE_API_KEY, but AI-powered analysis features will be disabled.

🏃 Running the Application

Development Mode

Start the Backend Server

cd server

# If using virtual environment, activate it first
# Windows: .\venv\Scripts\activate
# macOS/Linux: source venv/bin/activate

# Run the server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The API will be available at:

Start the Frontend Client

cd client

# Start development server
npm run dev

The frontend will be available at:

Production Build

Build Frontend

cd client
npm run build

The optimized build will be in client/dist/.

Run Backend (Production)

cd server
uvicorn main:app --host 0.0.0.0 --port 8000

📡 API Documentation

Base URL

http://localhost:8000

Core Endpoints

Health & Status

  • GET / - Root endpoint (system status)
  • GET /health - Health check endpoint

Genomics

  • GET /api/v1/genomics/status - Get genomics module status
  • POST /api/v1/genomics/upload - Upload SNP file (TSV/BED format)
  • POST /api/v1/genomics/parse - Parse genome file (alias for upload)
  • GET /api/v1/genomics/score - Get current Neuro-Resilience Score
  • POST /api/v1/genomics/analyze - Trigger AI analysis of genomics data

Patients

  • GET /patients - List all patients
  • GET /patients/{id} - Get patient by ID
  • POST /patients - Create new patient
  • PUT /patients/{id} - Update patient
  • DELETE /patients/{id} - Delete patient

Treatments

  • GET /treatments - List all treatments
  • GET /treatments/{id} - Get treatment by ID
  • POST /treatments - Create new treatment
  • PUT /treatments/{id} - Update treatment

Inventory

  • GET /inventory - List inventory items
  • GET /inventory/{id} - Get inventory item by ID
  • POST /inventory - Add inventory item
  • PUT /inventory/{id} - Update inventory item

Suppliers

  • GET /suppliers - List suppliers
  • GET /suppliers/{id} - Get supplier by ID
  • POST /suppliers - Create supplier

Statistics

  • GET /stats - Get system statistics
  • GET /stats/patients - Patient statistics
  • GET /stats/treatments - Treatment statistics

Brain AI

  • POST /brain/analyze - Analyze brain data with AI

Sensors

  • GET /sensors - Get sensor data
  • POST /sensors - Submit sensor readings

Session

  • GET /session - Get current session
  • POST /session - Create/start session
  • PUT /session - Update session

Imaging

  • POST /api/v1/imaging/upload - Upload MRI image
  • GET /api/v1/imaging/{id} - Get imaging analysis

Interactive API Documentation

Once the server is running, visit:

🛠️ Development

Code Style

  • Frontend:

    • ESLint configured for React/TypeScript
    • Prettier (recommended)
    • TypeScript strict mode enabled

  • Backend:

    • PEP 8 style guide
    • Type hints recommended
    • Async/await for I/O operations

Testing

# Frontend linting
cd client
npm run lint

# Backend (add tests as needed)
cd server
pytest  # If tests are added

Adding New Features

  1. Backend: Add new routers in server/routers/ and register in server/main.py
  2. Frontend: Add components in client/src/components/ and update routing in App.tsx

📊 Key Technologies

Frontend

  • React 19: UI framework
  • Vite: Build tool and dev server
  • TypeScript: Type safety
  • Tailwind CSS v4: Utility-first CSS
  • Zustand: Lightweight state management
  • Three.js / R3F: 3D graphics
  • Recharts: Data visualization
  • Axios: HTTP client
  • Framer Motion: Animations

Backend

  • FastAPI: Modern Python web framework
  • Uvicorn: ASGI server
  • Pandas: Data manipulation
  • NumPy: Numerical computing
  • Google Generative AI: Gemini integration
  • Python-dotenv: Environment configuration

🔒 Security Notes

  • CORS is configured for development (localhost:5173, localhost:3000)
  • For production, update CORS origins in server/main.py
  • API keys should be stored in environment variables (.env file)
  • Never commit .env files to version control

📝 License & Status

Status: Active Development (v2.0)

This project is part of the AI4Alzheimer's Hackathon challenge and is designed for research and educational purposes.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📚 Additional Documentation

🐛 Troubleshooting

Common Issues

Backend won't start:

  • Ensure Python 3.10+ is installed
  • Check that all dependencies are installed: pip install -r requirements.txt
  • Verify port 8000 is not in use
  • If using server.main:app, run from parent directory, or use main:app from server directory

Frontend won't start:

  • Ensure Node.js v20+ is installed
  • Clear node_modules and reinstall: rm -rf node_modules && npm install
  • Check that port 5173 is not in use

API 404 errors:

  • Ensure backend server is running
  • Check CORS configuration matches frontend URL
  • Verify endpoint paths match API documentation

Genomics analysis not working:

  • Check if GOOGLE_API_KEY is set in .env file
  • Without API key, basic analysis works but AI features are disabled

📧 Support

For issues, questions, or contributions, please open an issue on the repository.

Built with ❤️ for Alzheimer's Disease Research

Accomplishments that we're proud of

What we learned

What's next for AI for Alzheimer's

Built With

Share this project:

Updates