Brain Annex : Full-Stack Knowledge Management with Neo4j
HomeProgrammer's GuideDownload/InstallContact

Programmer's Guide

See also the README file.


The following Python and JavaScript libraries (python classes, unless otherwise specified) are being used:

FOUNDATIONAL LIBRARIES

Class NeoAccess

    IMPORTANT : for versions 4.x of the Neo4j database

    High-level class to interface with the Neo4j graph database from Python.

    Mostly tested on versions 4.3 and 4.4 of Neo4j Community version, but should work with other 4.x versions, too.
    NOT tested on any other major version of Neo4j; in particular, NOT tested with version 5

    Conceptually, there are two parts to NeoAccess:
        1) A thin wrapper around the Neo4j python connectivity library "Neo4j Python Driver"
          that is documented at: https://neo4j.com/docs/api/python-driver/current/api.html

        2) A layer above, providing higher-level functionality for common database operations,
           such as lookup, creation, deletion, modification, import, indices, etc.


NeoAccess differs from all other Brain Annex libraries in two important ways:

1) it's no longer in Beta

2) it's available thru the standard Python repository. You can just pip install neoaccess - which will take care of dependencies - and start using it with a simple: from neoaccess import NeoAccess

List of functions and their description
Source code

Class NeoSchema

    A layer above the class NeoAccess (or, in principle, another library providing a compatible interface)
    to provide an optional schema to the underlying database.

    Schemas may be used to either:
        1) acknowledge the existence of typical patterns in the data
        OR
        2) to enforce a mold for the data to conform to

    MOTIVATION

        Relational databases are suffocatingly strict for the real world.
        Neo4j by itself may be too anarchic.
        A schema (whether "lenient/lax/loose" or "strict") in conjunction with Neo4j may be the needed compromise.

    GOAL

        To infuse into Neo4j functionality that some people turn to RDF for.  However, carving out a new path
        rather than attempting to emulate RDF!
Background Information: Using Schema in Graph Databases such as Neo4j
List of functions and their description
Source code

DATA-MANAGER LAYER

Class APIRequestHandler

    For general database-interaction operations.
    Used by the UI for Page Generation,
    as well as by the API to produce data for the endpoints.

    This class does NOT get instantiated.
Source code

Class PagesRequestHandler

    Used by the UI for Page Generation.

    This class does NOT get instantiated.
Source code

PLUGIN-provided Handlers

    Each registered plugin may opt to provide python methods for its specific needs.
Source code

API LAYER

Class ApiRouting

    Setup, routing and endpoints for all the web pages served by this module.
    Note that this class does not directly interact with the Neo4j database.

    SECTIONS:
        - UTILITY methods
        - For DEBUGGING
        - ROUTING:
            * SCHEMA-related (reading)
            * SCHEMA-related (creating)
            * CONTENT-ITEM MANAGEMENT
                VIEWING CONTENT ITEMS
                MODIFYING EXISTING CONTENT ITEMS
            * CATEGORY-RELATED (incl. adding new Content Items)
                POSITIONING WITHIN CATEGORIES
            * FILTERS
            * IMPORT-EXPORT  (upload/download)
            * EXPERIMENTAL
Source code

Class ServerCommunication (JavaScript)

    STATIC class to communicate with the server using the fetch() API.

    Some methods are general; others implement one of the protocols detailed further down.
Source code

FLASK-PAGES LAYER

Class PagesRouting

    Setup and routing for all the Flask-based web pages served by this module
Source code

Flask Templates (HTML)

    HTML Flask templates for the various pages of the Brain-Annex provided site (including administrative pages and category-viewer pages)
Source code

Static Assets (CSS and JavaScript, including Vue.js components)

    For the various site pages
Source code

TOP LEVEL

MAIN PROGRAM

    It starts up a server for web User Interface and an API
    Run this file, and then set the browser to http://localhost:5000/some_url
    (the actual port number is configurable; the URL's are specified in the various modules)

    IMPORTANT: first change the config.ini file as needed
    
    Note: this main program may also be started from the CLI with the "flask run" command
Source code

Class InitializeBrainAnnex

    INITIALIZATION of various static classes
Source code

NAVIGATION

Class Navigation

    Router/generator for navigation pages:
        CSS static pages, and HTML pages that get included into other Flask files
        
    Setup, and routing, for all the web pages
Source code

Function get_site_pages()

    Definition of the Navigation Bar entries for the overall site navigation
    (both Brain Annex and, possibly, co-hosted sites)
Source code

OTHER LIBRARIES

Class Categories

    Library for Category-related operations.
    
    An entity to which a variety of nodes (e.g. representing records or media)
    is attached, with a positional attribute.
    
    Categories also have "subcategory" relationships with other categories.

    Contains the following groups of methods:
        1. LOOKUP
        2. UPDATE
        3. POSITIONING WITHIN CATEGORIES
Source code

Class Collections

    A generalization of Categories.
    
    An entity to which a variety of nodes (e.g. representing records or media)
    is attached, with a positional attribute.
Source code

Class FullTextIndexing

    Indexing-related methods.  In early development stage
Source code

Class ImageProcessing

    Utility class for managing images, especially in the context of uploads.
Source code

Class MediaManager

    Helper library for the management of media files
Source code

Class NodeExplorer

    A largely experimental library to deal with management and visualization of data nodes
Source code

Class UploadHelper

    Helper class to manage file uploads with Flask 1.1 (using Werkzeug 2.1)
Source code

Utilities

    General utilities for comparisons and pandas
Source code