# arus-info/projectit architecture

> Architecture diagram of the GitHub repository arus-info/projectit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arus-info/projectit
- Repository: https://github.com/arus-info/projectit

## Overview

##### Project type and purpose
- ProjectIT is a full-stack solution consisting of:
– A Vue-based Progressive Web App (PWA) front end under the “mobile/” folder
– A Frappe Framework Python back end (the “projectit/” Python package) integrated with ERPNext and Frappe HR
– A MariaDB (or compatible) database managed by Frappe
- Purpose: Track field employees’ check-ins, GPS, photos, timesheets and send real-time instructions.

##### Main components
A. Mobile PWA (Frontend)
– Built with Vue 3, Vite, Tailwind CSS
– Service Worker (mobile/public/sw.js) for offline support
– Core pages (mobile/src/pages/*), components and composables for:
- Authentication (Login.vue)
- Check-In/Out, Camera.vue, GPS
- TimesheetEntry.vue, WorkInstructions.vue, etc.
B. Frappe Backend (ERPNext App)
– Python modules under projectit/ (api.py, hooks.py, doctype definitions)
– Doctypes: employee_allocation_instruction, mobile_module, work_time_settings, etc.
– REST HTTP API endpoints auto-exposed by Frappe + any custom API in api.py
– Fixtures and patches for initial data (projectit/fixtures)
C. ERPNext & Frappe HR
– Existing ERPNext Project and HR modules that this app extends
– Schema linkages between ProjectIT doctypes and ERPNext doctypes
D. Database
– MariaDB (or similar) where Frappe stores doctypes, user sessions, attachments
E. External browser APIs
– Geolocation API
– Camera/File API for photos
F. Network & Security
– HTTPS channel between PWA and Frappe server
– Authentication via Frappe session tokens or JWT

##### Relationships and data flows
- On app launch, the PWA checks for service worker updates → auth flow via Frappe HTTP API → session cookie/token
- User actions (e.g., Check-In) invoke Vue composable → send JSON payload (GPS, photo) to Frappe API
- Frappe controller (doctype Python code or api.py) validates and writes to MariaDB
- Real-time status updates: PWA polls or uses Frappe real-time events (socket) → updates UI
- Project managers view instructions/allocations via PWA pages backed by Frappe REST endpoints

##### Architectural patterns and design principles
– MVC in Frappe:
- Model = Doctypes (+ JSON schemas under projectit/projectit/doctype)
- View = Jinja templates (projectit/templates/pages) & PWA UI
- Controller = Python API endpoints (api.py, hooks.py)
– PWA pattern: service worker, web manifest (handled in index.html), offline caching
– Separation of concerns: UI in “mobile/”, business logic and data access in Frappe app
– Extensibility via Frappe hooks and fixtures

##### Essential elements
- Notes for service-worker caching strategy

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Browser APIs
    subgraph "Browser APIs" 
        direction TB
        Geo["Geolocation API"]:::external
        Cam["Camera/File API"]:::external
    end

    %% Mobile PWA Frontend
    subgraph "Vue 3 PWA Frontend" 
        direction TB
        SW["Service Worker"]:::frontend
        Manifest["Web Manifest & Entry HTML"]:::frontend
        MainJS["Main JS Entry & App Initialization"]:::frontend
        Router["Vue Router Configuration"]:::frontend
        Styles["Global Styles & Tailwind Config"]:::frontend
        Vite["Vite Build Config"]:::frontend

        subgraph "Pages & Views"
            direction TB
            Login["Login.vue"]:::frontend
            Timesheet["TimesheetEntry.vue"]:::frontend
            InstructionsPage["WorkInstructions.vue"]:::frontend
            subgraph "Check-In/Out Pages"
                direction TB
                Allocate["AllocateEmployees.vue"]:::frontend
                InstrPage["Instructions.vue"]:::frontend
                WorkIT["WorkIT.vue"]:::frontend
            end
        end

        subgraph "UI Components"
            direction TB
            CamComp["Camera.vue"]:::frontend
            Button["PrimaryButton.vue"]:::frontend
            List["ListView.vue"]:::frontend
            ErrorMsg["ErrorMessage.vue"]:::frontend
        end

        subgraph "Composables & State"
            direction TB
            IndexComp["index.js"]:::frontend
            Session["session.js"]:::frontend
            UserData["user.js"]:::frontend
            CamCtx["camera_context.js"]:::frontend
            WorkInst["work_instructions.js"]:::frontend
            ModuleData["module.js"]:::frontend
        end
    end

    %% Frappe Backend
    subgraph "Frappe Backend (ProjectIT App)" 
        direction TB
        API["api.py"]:::backend
        Hooks["hooks.py"]:::backend
        Configs["modules.txt / patches.txt / config"]:::backend

        subgraph "Doctypes"
            direction TB
            DOI["employee_allocation_instruction.py"]:::backend
            MM["mobile_module.py"]:::backend
            MMI["mobile_module_item.py"]:::backend
            PAI["project_allocation_and_instrucions.py"]:::backend
            WTS["work_time_settings.py"]:::backend
        end

        subgraph "JSON Schemas & Client Scripts"
            direction TB
            JSONS["*.json"]:::backend
            MMIJS["mobile_module_item.js"]:::backend
            PAIJS["project_allocation_and_instrucions.js"]:::backend
            WTSJS["work_time_settings.js"]:::backend
        end

        subgraph "Tests & Fixtures"
            direction TB
            Tests["test_*.py"]:::backend
            Fixtures["fixtures/*.json"]:::backend
        end

        BizLogic["project.py / timesheet.py"]:::backend
        Templates["templates/pages"]:::backend
        PublicJS["public/js/project.js"]:::backend
    end

    %% ERPNext & Database
    subgraph "ERPNext & Database"
        direction TB
        ERP["ERPNext Core Modules"]:::backend
        DB["MariaDB / Frappe DB"]:::db
    end

    %% Data Flows
    User["User"]:::external
    User -->|"Interacts"| Login
    User -->|"Grants Permission"| Geo
    User -->|"Grants Permission"| Cam

    Geo -->|Provides GPS| IndexComp
    Cam -->|Captures Photo| CamComp

    Login -->|Auth Flow HTTP| API
    MainJS -->|Bootstrap App| Router
    Router --> Login
    Router --> Timesheet
    Router --> InstructionsPage
    Router --> Allocate

    CamComp -->|Uses SW Cache| SW
    SW -->|Caches| Styles
    SW -->|Caches| MainJS

    IndexComp -->|"POST /api/method/projectit.api.check_in"| API
    WorkInst -->|"GET instructions"| API
    API -->|"Validate & Save"| DOI
    BizLogic -->|"Business Logic"| DOI
    API --> ERP
    API --> DB
    ERP --> DB

    %% Click Events
    click SW "https://github.com/arus-info/projectit/blob/main/mobile/public/sw.js"
    click Manifest "https://github.com/arus-info/projectit/blob/main/mobile/index.html"
    click MainJS "https://github.com/arus-info/projectit/blob/main/mobile/src/main.js"
    click Router "https://github.com/arus-info/projectit/blob/main/mobile/src/router.js"
    click Styles "https://github.com/arus-info/projectit/blob/main/mobile/src/index.css"
    click Styles "https://github.com/arus-info/projectit/blob/main/mobile/tailwind.config.js"
    click Vite "https://github.com/arus-info/projectit/blob/main/mobile/vite.config.js"
    click Login "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/Login.vue"
    click Timesheet "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/TimesheetEntry.vue"
    click InstructionsPage "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/WorkInstructions.vue"
    click Allocate "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/AllocateEmployees.vue"
    click InstrPage "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/Instructions.vue"
    click WorkIT "https://github.com/arus-info/projectit/blob/main/mobile/src/pages/WorkIT.vue"
    click CamComp "https://github.com/arus-info/projectit/blob/main/mobile/src/components/Camera.vue"
    click Button "https://github.com/arus-info/projectit/blob/main/mobile/src/components/PrimaryButton.vue"
    click List "https://github.com/arus-info/projectit/blob/main/mobile/src/components/ListView.vue"
    click ErrorMsg "https://github.com/arus-info/projectit/blob/main/mobile/src/components/ErrorMessage.vue"
    click IndexComp "https://github.com/arus-info/projectit/blob/main/mobile/src/composables/index.js"
    click Session "https://github.com/arus-info/projectit/blob/main/mobile/src/data/session.js"
    click UserData "https://github.com/arus-info/projectit/blob/main/mobile/src/data/user.js"
    click CamCtx "https://github.com/arus-info/projectit/blob/main/mobile/src/data/camera_context.js"
    click WorkInst "https://github.com/arus-info/projectit/blob/main/mobile/src/data/work_instructions.js"
    click ModuleData "https://github.com/arus-info/projectit/blob/main/mobile/src/data/module.js"
    click API "https://github.com/arus-info/projectit/blob/main/projectit/api.py"
    click Hooks "https://github.com/arus-info/projectit/blob/main/projectit/hooks.py"
    click Configs "https://github.com/arus-info/projectit/blob/main/projectit/modules.txt"
    click DOI "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/employee_allocation_instruction/employee_allocation_instruction.py"
    click MM "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/mobile_module/mobile_module.py"
    click MMI "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/mobile_module_item/mobile_module_item.py"
    click PAI "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/project_allocation_and_instrucions/project_allocation_and_instrucions.py"
    click WTS "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/work_time_settings/work_time_settings.py"
    click MMIJS "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/mobile_module_item/mobile_module_item.js"
    click PAIJS "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/project_allocation_and_instrucions/project_allocation_and_instrucions.js"
    click WTSJS "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/work_time_settings/work_time_settings.js"
    click Tests "https://github.com/arus-info/projectit/blob/main/projectit/projectit/doctype/mobile_module_item/test_mobile_module_item.py"
    click Fixtures "https://github.com/arus-info/projectit/blob/main/projectit/fixtures/custom_field.json"
    click BizLogic "https://github.com/arus-info/projectit/blob/main/projectit/projectit/project.py"
    click PublicJS "https://github.com/arus-info/projectit/blob/main/projectit/public/js/project.js"
    click Templates "https://github.com/arus-info/projectit/tree/main/projectit/templates/pages/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#000
    classDef backend fill:#FFF9C4,stroke:#F57F17,color:#000
    classDef db fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#000
```
