Skip to content

Codebase Map

This page explains where logic lives so a new contributor can quickly choose the right codebase to modify.

Repository-Level View

flowchart LR
    subgraph FE[frontend]
      FE_APP[src/app]
      FE_COMP[src/components]
      FE_CTX[src/context]
      FE_SVC[src/services]
      FE_LIB[src/lib/axios.ts]
    end

    subgraph BE[backend]
      BE_API[app/api]
      BE_CORE[app/core]
      BE_CRUD[app/crud]
      BE_SCHEMA[app/schemas]
      BE_SERVICE[app/services]
      BE_AGENT[app/agent_v2]
      BE_WORKER[Celery workers]
    end

    subgraph MO[mobile]
      MO_LIB[lib/screens + services]
      MO_CH[LlmPlatformChannel]
      MO_NATIVE[android/MainActivity.kt]
      MO_INF[InferenceModel.kt]
      MO_STORE[SharedPreferences + local files]
    end

    FE_SVC -->|HTTP REST| BE_API
    FE_LIB --> FE_SVC
    BE_API --> BE_SERVICE
    BE_API --> BE_CRUD
    BE_SERVICE --> BE_AGENT
    BE_API --> BE_WORKER

    MO_LIB --> MO_CH
    MO_CH --> MO_NATIVE
    MO_NATIVE --> MO_INF
    MO_LIB -->|HTTP REST| BE_API

Ownership Boundaries

  1. frontend owns rendering, route-level UX, form handling, dashboard interactions, and web chatbot UI.
  2. backend owns business rules, persistence, auth verification, AI orchestration, and final operational state transitions.
  3. mobile owns field capture UX, local model lifecycle, offline generation, and sync handoff to backend APIs.

Integration Contracts

1. Auth Contract

  • Clients attach Authorization: Bearer <firebase_id_token>.
  • Backend verifies Firebase token before protected operations.

2. API Contract

  • Web and mobile call the same backend REST resources (/requests, /tasks, /resources, /chatbot/ask, /workflow-outputs).
  • Backend remains the source of truth for operational entities.

3. Async/AI Contract

  • API enqueues long-running or agentic work through Redis.
  • Celery workers execute workflows and persist outputs to Firestore collections.

4. Mobile Runtime Contract

  • Offline generation is handled locally through Android bridge + MediaPipe model.
  • When network is available, mobile syncs user actions and model-assisted outcomes to backend.

Where To Start As A New Contributor

  1. Read docs/system-overview/index.md and docs/system-overview/dataflow.md.
  2. For UI changes, start from frontend/src/app route and trace into src/services.
  3. For backend features, start from endpoint in backend/app/api, then follow service/crud/agent layers.
  4. For mobile/offline behavior, start at mobile/lib/screens and trace through LlmPlatformChannel into Kotlin runtime files.