Skip to content

help_support.md

Latest commit

 

History

History
165 lines (128 loc) · 6.97 KB

help_support.md

File metadata and controls

165 lines (128 loc) · 6.97 KB
Raw

DIRA — Developer Help & Support Guide

Welcome to DIRA! This guide is designed to onboard new developers and contributors to the codebase, explain the architecture of the system, and provide common troubleshooting steps and support resources.

🗺️ Repo Overview & Architecture

DIRA is a market intelligence stack tailored for informal vendor workflows. The system is split into three main runtime components, a database, and a setup script that orchestrates local development.

graph TD
    Client[WhatsApp Client / Web User] -->|Interact| WA_Bridge[WhatsApp Bridge Node.js]
    Client -->|Web UI| Frontend[React Frontend Vite]
    WA_Bridge -->|API Request| Backend[FastAPI Backend]
    Frontend -->|API Request| Backend
    Backend -->|Read/Write| DB[(PostgreSQL Database)]
Loading

1. Backend (dira_agent/)

  • Technology: Python 3, FastAPI, SQLAlchemy (ORM), Alembic (migrations).
  • Purpose: Serves the REST API, coordinates LLM analysis (powered by Gemini), manages database models, and processes incoming data from both the web frontend and the WhatsApp bridge.
  • Entry point: dira_agent/main.py

2. Frontend (frontend/)

  • Technology: React, Vite, Vanilla CSS.
  • Purpose: Provides a clean web application interface to view collected market intelligence, manage workflows, and inspect incoming vendor reports.
  • Entry point: frontend/src/main.jsx

3. WhatsApp Bridge (whatsapp_bridge/)

  • Technology: Node.js, Baileys library (WhatsApp Web API client).
  • Purpose: Bridges the physical messaging channel used by informal vendors (WhatsApp) to the backend. It handles session storage, processes incoming messages, and triggers backend endpoints.
  • Entry point: whatsapp_bridge/index.js

⚡ Quick Start: Running the Stack

The easiest way to start developing is to run the automated workspace orchestration script from the repository root:

./dev.sh up

What ./dev.sh up does automatically:

  1. Configures Environment: Copies .env.example to .env if it doesn't exist.
  2. Postgres Setup: Launches a Postgres container via Docker Compose.
  3. Dependency Installation:
    • Creates a Python virtual environment (.venv) and installs dira_agent/requirements.txt.
    • Runs npm install in both /frontend and /whatsapp_bridge.
  4. Port Resolution: Checks if default ports (5173 for frontend, 8000 for backend, 3000 for bridge) are occupied, picks the next available ones, and spins up the servers.
  5. Liveness Monitoring: Waits until the health check endpoints are active and outputs the exact URLs to click.

🛠️ Common Developer Workflows

🗄️ Database Migrations (Alembic)

When modifying tables or fields in dira_agent/app/models/, you must generate and apply migrations.

  1. Activate the Backend Virtual Environment: 
    cd dira_agent
source .venv/bin/activate
  2. Generate a new migration: 
    alembic revision --autogenerate -m "describe your changes here"
  3. Apply migrations: 
    alembic upgrade head

🧪 Running Quality & Test Suites

Always run the validation suite before pushing code to avoid CI breakage:

  • Backend Tests: 
    cd dira_agent
source .venv/bin/activate
python -m pytest -q tests
  • Frontend Linting & Production Build: 
    cd frontend
npm run lint
npm run build
  • Full Local Smoke Test: To quickly spin up the stack, assert that health endpoints respond, and shut down: 
    ./dev.sh test

💬 Working with the WhatsApp Bridge

The WhatsApp bridge enables the platform to interact with real WhatsApp clients.

🔑 Authentication & QR Pairing

  1. Run the bridge (either via ./dev.sh up or manually with node index.js inside whatsapp_bridge/).
  2. The terminal output will prompt you with a QR Code or a pairing code.
  3. Open WhatsApp on your mobile phone, navigate to Linked Devices -> Link a Device, and scan the QR code.
  4. Once authenticated, a session state is saved in whatsapp_bridge/auth_info_baileys/.

Warning

Security Risk: Never commit the whatsapp_bridge/auth_info_baileys/ directory to git. This folder contains live session tokens that grant control of your WhatsApp account. It is pre-configured in the .gitignore file, but always double-check.

🚨 Troubleshooting Common Issues

1. Docker/Postgres Permissions Error

If running ./dev.sh fails because Docker requires sudo, the script will attempt a retry with sudo. If this still fails:

  • Run Docker post-installation steps to add your user to the docker group: 
    sudo usermod -aG docker $USER
    (Remember to log out and log back in for changes to take effect).

2. Port Mismatch or Port Already in Use

If a service is stuck or didn't shut down cleanly from a previous session, a port might remain occupied.

  • ./dev.sh automatically attempts to find and terminate processes holding the default ports, but if you need to do it manually: 
    # Find what is running on port 8000
lsof -i :8000
# Or kill it
kill -9 $(lsof -t -i:8000)

3. Missing python3-venv on Ubuntu/Debian

If the setup script fails while creating the .venv virtual environment:

  • Install the virtual environment system package: 
    sudo apt update && sudo apt install python3-venv python3-pip -y

🌍 Environment Configurations

The system is configured via a single shared .env file at the root of the repository.

Key Description Example / Recommended
POSTGRES_USER Postgres DB administrator name dira_user
POSTGRES_PASSWORD Postgres DB administrator password Use a strong secret
POSTGRES_DB Target database name dira_db
APP_ENV Mode for the stack (development or production) development
DATABASE_URL DB connection string postgresql://dira_user:password@localhost/dira_db
JWT_SECRET Secret key used to sign session tokens Use a strong random string
GEMINI_API_KEY Key for automated market analysis Obtained from Google AI Studio
ADMIN_EMAIL Configures the email auto-assigned the admin role. Critical: Registration under this email creates the primary administrative account necessary for configuring and authorizing secure WhatsApp bridge sessions. admin@dira.local

🆘 Where to Get Support

  • Architecture and Refactoring: Refer to the architecture documentation at docs/architecture.md (when generated) or view the PDF system report docs/SB30_PU_40198_21_Emmanuel Munubi - Dira_Report.pdf for detailed domain and academic context.
  • API Documentation: Once the backend is running, the interactive OpenAPI dashboard is available at:
    • http://127.0.0.1:8000/docs
  • Issues & Questions: Connect with Emmanuel Munubi or open a GitHub issue on the repository to discuss features, report bugs, or request assistance.