# suryodaya27/ai-journal-backend architecture

> Architecture diagram of the GitHub repository suryodaya27/ai-journal-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suryodaya27/ai-journal-backend
- Repository: https://github.com/suryodaya27/ai-journal-backend

## Overview

##### Project Type & Purpose
- This is a single-service backend application (“monolith”) that exposes REST APIs for journaling, integrates with AI services to derive insights, and runs background/cron jobs for summaries, goals, and reflections.

##### File Structure
- Top-level configuration: Dockerfile, docker-compose.yml, Prisma schema & migrations.
- src/index.js: Express app entry point.
- src/routes & src/controller: HTTP API layer (Auth, Journal entries, Goals/Suggestions/Reminders).
- src/middleware: Auth checks.
- src/utils: Redis client, caching/rate-limit functions, Google Gemini integration, seed scripts.
- src/jobs & src/cron-jobs:
- Cron jobs schedule weekly/monthly summary/reflection tasks.
- BullMQ jobs handle queued tasks (batching entries, processing with AI, saving results).
- Redis used both as cache and as the BullMQ broker.
- Prisma + PostgreSQL for persistent storage of users, journals, insights, goals.

##### README for Architectural Insights
- Express.js backend (handles incoming requests).
- BullMQ (Redis) for asynchronous task processing.
- Google Gemini API for AI-driven analysis.
- Redis for caching & rate limiting.
- Cron jobs for periodic insights and reflections.
- PostgreSQL accessed via Prisma ORM.

##### Main Components & Interactions
a. API Layer
- Express.js server exposes endpoints (auth, journal, goals/suggestions).
- Controllers implement business logic and orchestrate DB or queue operations.
b. Database
- PostgreSQL with Prisma ORM: stores user data, journal entries, AI insights, goals, reminders.
c. Cache / Queue Broker
- Redis:
- Caches frequently accessed data or rate-limits requesters.
- Serves as the BullMQ message broker.
d. Task Queue & Workers
- BullMQ: enqueues jobs from controllers or cron-jobs.
- Worker processes (src/jobs/bullMqProcessor.js) consume jobs, call AI, batch DB writes.
e. Cron Scheduler
- Cron jobs trigger on schedule to enqueue summary/reflection jobs.
f. External AI Service
- Google Gemini API for generating insights, summaries, goals.
g. Optional Components
- Docker & docker-compose for local orchestration.

##### Architectural Patterns & Design Principles
- Layered architecture:
- Presentation/API (Express + Routes + Controllers)
- Business logic (Controllers + Services in utils/jobs)
- Data layer (Prisma + PostgreSQL)
- Asynchronous processing pattern using message queues (BullMQ).
- Cache-aside & rate-limiting with Redis.
- Cron scheduling for periodic tasks.
- Fault tolerance: retry logic built into AI calls & job processors.
- Modular separation: controllers, middleware, utils, cron-jobs, jobs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client/Consumer"]:::external

    %% API Layer
    subgraph "API Server"
        direction TB
        Index["src/index.js\n(Express Entry)"]:::backend
        subgraph "Routes"
            direction TB
            AuthRoutes["Auth Routes"]:::backend
            JournalRoutes["Journal Routes"]:::backend
            GoalsRoutes["Goals/Suggestions/Reminders Routes"]:::backend
        end
        subgraph "Controllers"
            direction TB
            AuthController["Auth Controller"]:::backend
            JournalController["Journal Entries Controller"]:::backend
            GoalsController["Goals/Suggestions/Reminders Controller"]:::backend
        end
        Middleware["Auth Middleware"]:::backend
    end

    %% Cache & Queue Broker
    Redis["Redis\n(Cache & Broker)"]:::cache

    %% Cron Scheduler
    subgraph "Cron Scheduler"
        direction TB
        InsightsCron["createInsights.cronjob.js"]:::cron
        SummaryCron["createSummaryAndGoals.js"]:::cron
        ReflectionCron["reflection.cronjob.js"]:::cron
    end

    %% Workers
    subgraph "Workers"
        direction TB
        Processor["bullMqProcessor.js"]:::worker
        Batcher["entriesBatcher.js"]:::worker
    end

    %% Database
    PostgreSQL["PostgreSQL\n(Prisma ORM)"]:::db

    %% External AI
    Gemini["Google Gemini API"]:::external

    %% Docker Orchestration
    subgraph "Containerization"
        Dockerfile["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
    end

    %% Flows
    Client -->|HTTP Request| Index
    Index -->|"loads"| AuthRoutes
    Index -->|"loads"| JournalRoutes
    Index -->|"loads"| GoalsRoutes
    AuthRoutes -->|"calls"| AuthController
    JournalRoutes -->|"calls"| JournalController
    GoalsRoutes -->|"calls"| GoalsController
    AuthController -->|"uses"| Middleware
    JournalController -->|"uses"| Middleware
    GoalsController -->|"uses"| Middleware

    AuthController -->|"sync DB ops (Prisma)"| PostgreSQL
    JournalController -->|"enqueue job"| Redis
    GoalsController -->|"sync DB ops (Prisma)"| PostgreSQL

    JournalController -->|"HTTP Cache check"| Redis

    InsightsCron -->|"schedule job"| Redis
    SummaryCron -->|"schedule job"| Redis
    ReflectionCron -->|"schedule job"| Redis

    Redis -->|"push job"| Processor
    Processor -->|"batch entries"| Batcher
    Batcher -->|"write insights"| PostgreSQL
    Processor -->|"call AI"| Gemini
    Processor -->|"write insights"| PostgreSQL

    %% Legend
    subgraph "Legend"
        direction TB
        A["Blue = HTTP/API"]:::http
        B["Orange = Async Queue"]:::async
        C["Green = External Service"]:::external
        D["Gray = Database"]:::db
    end

    %% Click Events
    click Index "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/index.js"
    click AuthRoutes "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/routes/auth.routes.js"
    click JournalRoutes "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/routes/journal.routes.js"
    click GoalsRoutes "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/routes/goalsAndSuggestions.routes.js"
    click AuthController "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/controller/auth.controller.js"
    click JournalController "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/controller/journal.controller.js"
    click GoalsController "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/controller/goalsAndSuggestionsAndReminders.controller.js"
    click Middleware "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/middleware/auth.middleware.js"
    click Processor "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/jobs/bullMqProcessor.js"
    click Batcher "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/jobs/entriesBatcher.js"
    click InsightsCron "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/cron-jobs/createInsights.cronjob.js"
    click SummaryCron "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/cron-jobs/createSummaryAndGoals.js"
    click ReflectionCron "https://github.com/suryodaya27/ai-journal-backend/blob/main/src/cron-jobs/reflection.cronjob.js"

    %% Styles
    classDef backend fill:#D6E9FF,stroke:#1E90FF,stroke-width:1px
    classDef cache fill:#FFF2CC,stroke:#F0AD4E,stroke-width:1px
    classDef worker fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef cron fill:#FFE4E1,stroke:#FF69B4,stroke-width:1px
    classDef db fill:#E0E0E0,stroke:#636363,stroke-width:1px
    classDef external fill:#E6FFED,stroke:#28A745,stroke-width:1px
    classDef infra fill:#F5F5F5,stroke:#A9A9A9,stroke-width:1px
    classDef http stroke:#1E90FF,stroke-width:2px
    classDef async stroke:#FF8C00,stroke-width:2px
```
