# ocdevel/gnothi architecture

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

- Interactive diagram: https://gitdiagram.com/ocdevel/gnothi
- Repository: https://github.com/ocdevel/gnothi

## Overview

##### Project type and purpose
- This is a full-stack, serverless journaling and AI toolkit called “Gnothi.”
- The frontend is a React/TypeScript single-page app in the web/ directory.
- The backend is composed of multiple serverless microservices (Node.js and Python Lambdas) managed by SST (stacks/*.ts).
- It integrates with AWS (API Gateway, Lambda, Aurora Serverless Postgres, VPC, SES, Logs, etc.) and external ML APIs (OpenAI).

##### File structure
- Top level: Docker-based local development (docker-compose.yml), SST config (sst.config.ts), stacks/ directory (infrastructure definitions).
- web/: React frontend, UI components, routing, data store, API client.
- services/: source for all Lambda handlers and domain logic:
– services/routes: HTTP routes (Admin, Books, Entries, Fields, Groups, Insights, Notifs, Shares, Stripe, Tags, Users).
– services/auth: custom authorizers, triggers (Cognito, WebSocket auth).
– services/data: data-access layer, migrations, ORM models, DB singleton (Node TS).
– services/ml: Node Lambda wrappers and Python containerized Lambdas for AI tasks (ask, behaviors, books, preprocess, store, summarize).
- schemas/: shared TypeScript types for API contracts.
- stacks/: high-level SST constructs grouping microservices into API, Auth, ML, Web, Logs, SES, etc.

##### README for additional insights
- Confirms it’s an SST site: each “local” run still deploys into a VPC (private subnets, NAT gateway), Aurora Serverless v2, SES, CloudWatch.
- Developer setup involves Docker Compose for local emulation of the DB and ML containers.

##### Elements
– Frontend (blue),
– API Gateway & Lambdas (green),
– Database (orange),
– AWS Infra (gray),
- Containers:
– “AWS Cloud” boundary encompassing API Gateway, Lambdas, DB, VPC, SES, CloudWatch.
– “Local Dev” boundary for Docker Compose services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        User["User"]:::external
        SPA["React SPA"]:::frontend
    end
    User -->|interacts| SPA

    %% Local Development
    subgraph "Local Development"
        DC["Docker Compose"]:::infra
        PostgresLocal[(Postgres Local)]:::db
        MLContainer["Python ML Containers"]:::lambda
    end
    SPA -->|HTTP calls| APIGW

    %% AWS Cloud Boundary
    subgraph "AWS Cloud"
        %% API Layer
        subgraph "API Layer"
            APIGW["API Gateway HTTP"]:::infra
            APIGWWS["API Gateway WebSocket"]:::infra
        end

        %% Auth Lambdas
        subgraph "Auth Lambdas"
            AppAuth["appAuth.ts"]:::lambda
            Triggers["triggers.ts"]:::lambda
            WSAuth["wsAuthorizer.ts"]:::lambda
        end
        APIGWWS -->|authorize| WSAuth
        APIGW -->|auth triggers| AppAuth
        APIGW -->|invoke triggers| Triggers

        %% REST Lambdas
        subgraph "REST Lambdas"
            Index["index.ts"]:::lambda
            Errors["errors.ts"]:::lambda
            Admin["services/routes/admin"]:::lambda
            Books["services/routes/books"]:::lambda
            Entries["services/routes/entries"]:::lambda
            Fields["services/routes/fields"]:::lambda
            Groups["services/routes/groups"]:::lambda
            Insights["services/routes/insights"]:::lambda
            Notifs["services/routes/notifs"]:::lambda
            Shares["services/routes/shares"]:::lambda
            Stripe["services/routes/stripe"]:::lambda
            Tags["services/routes/tags"]:::lambda
            Users["services/routes/users"]:::lambda
        end
        APIGW -->|invoke| Index
        Index -->|routes to| Admin
        Index --> Books
        Index --> Entries
        Index --> Fields
        Index --> Groups
        Index --> Insights
        Index --> Notifs
        Index --> Shares
        Index --> Stripe
        Index --> Tags
        Index --> Users
        Index --> Errors

        %% Data Layer
        subgraph "Data Layer"
            DB[(Aurora Serverless Postgres)]:::db
            DBSingleton["dbSingleton.ts"]:::lambda
            DBConn["db.ts"]:::lambda
            Models["models/"]:::lambda
            Migrations["migrate/"]:::lambda
        end
        Entries -->|DB access| DBConn
        Fields --> DBConn
        Groups --> DBConn
        Books --> DBConn
        DBConn -->|singleton| DBSingleton
        DBSingleton --> Models
        DBSingleton --> Migrations
        DBConn --> DB

        %% ML Lambdas
        subgraph "ML Lambdas"
            MLNode["services/ml/node"]:::lambda
            MLPython["services/ml/python"]:::lambda
        end
        Insights --> MLNode
        Shares --> MLNode
        MLNode -->|calls| MLPython
        MLNode -->|OpenAI| OpenAI
        MLPython -->|OpenAI| OpenAI

        %% AWS Clients & Handlers
        subgraph "AWS Clients & Handlers"
            Clients["clients.ts"]:::lambda
            Handlers["handlers.ts"]:::lambda
            AWSLogs["logs.ts"]:::lambda
        end

        %% Infrastructure as Code
        subgraph "Infrastructure as Code"
            SSTCFG["sst.config.ts"]:::infra
            Stacks["stacks/"]:::infra
            Schemas["schemas/"]:::infra
        end

        %% AWS Services
        subgraph "AWS Services"
            SES["SES"]:::infra
            Logs["CloudWatch Logs"]:::infra
            VPC["VPC"]:::infra
            NAT["NAT Gateway"]:::infra
        end

        %% Main Entrypoint
        Main["services/main.ts"]:::lambda

    end

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Flows
    SPA -->|HTTP calls| APIGW
    APIGW --> Index
    Index --> DB
    REST_Lambdas--> SES
    AllLambdas--> Logs

    %% Click Events
    click SPA "https://github.com/ocdevel/gnothi/tree/main/web/"
    click DC "https://github.com/ocdevel/gnothi/blob/main/docker-compose.yml"
    click PostgresLocal "https://github.com/ocdevel/gnothi/blob/main/docker-compose.yml"
    click MLContainer "https://github.com/ocdevel/gnothi/blob/main/docker-compose.yml"
    click SSTCFG "https://github.com/ocdevel/gnothi/blob/main/sst.config.ts"
    click Stacks "https://github.com/ocdevel/gnothi/tree/main/stacks/"
    click Schemas "https://github.com/ocdevel/gnothi/tree/main/schemas/"
    click AppAuth "https://github.com/ocdevel/gnothi/blob/main/services/auth/appAuth.ts"
    click Triggers "https://github.com/ocdevel/gnothi/blob/main/services/auth/triggers.ts"
    click WSAuth "https://github.com/ocdevel/gnothi/blob/main/services/auth/wsAuthorizer.ts"
    click Clients "https://github.com/ocdevel/gnothi/blob/main/services/aws/clients.ts"
    click Handlers "https://github.com/ocdevel/gnothi/blob/main/services/aws/handlers.ts"
    click AWSLogs "https://github.com/ocdevel/gnothi/blob/main/services/aws/logs.ts"
    click DBConn "https://github.com/ocdevel/gnothi/blob/main/services/data/db.ts"
    click DBSingleton "https://github.com/ocdevel/gnothi/blob/main/services/data/dbSingleton.ts"
    click Models "https://github.com/ocdevel/gnothi/tree/main/services/data/models/"
    click Migrations "https://github.com/ocdevel/gnothi/tree/main/services/data/migrate/"
    click Admin "https://github.com/ocdevel/gnothi/tree/main/services/routes/admin/"
    click Books "https://github.com/ocdevel/gnothi/tree/main/services/routes/books/"
    click Entries "https://github.com/ocdevel/gnothi/tree/main/services/routes/entries/"
    click Fields "https://github.com/ocdevel/gnothi/tree/main/services/routes/fields/"
    click Groups "https://github.com/ocdevel/gnothi/tree/main/services/routes/groups/"
    click Insights "https://github.com/ocdevel/gnothi/tree/main/services/routes/insights/"
    click Notifs "https://github.com/ocdevel/gnothi/tree/main/services/routes/notifs/"
    click Shares "https://github.com/ocdevel/gnothi/tree/main/services/routes/shares/"
    click Stripe "https://github.com/ocdevel/gnothi/tree/main/services/routes/stripe/"
    click Tags "https://github.com/ocdevel/gnothi/tree/main/services/routes/tags/"
    click Users "https://github.com/ocdevel/gnothi/tree/main/services/routes/users/"
    click Index "https://github.com/ocdevel/gnothi/blob/main/services/routes/index.ts"
    click Errors "https://github.com/ocdevel/gnothi/blob/main/services/routes/errors.ts"
    click MLNode "https://github.com/ocdevel/gnothi/tree/main/services/ml/node/"
    click MLPython "https://github.com/ocdevel/gnothi/tree/main/services/ml/python/"
    click Main "https://github.com/ocdevel/gnothi/blob/main/services/main.ts"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef lambda fill:#E6FFED,stroke:#2F8F2F,color:#2F8F2F
    classDef db fill:#FFE6C7,stroke:#D78B00,color:#D78B00
    classDef infra fill:#F0F0F0,stroke:#888888,color:#555555
    classDef external stroke-dasharray: 5 5,color:#999999
```
