# pawafulu7/techtrend architecture

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

- Interactive diagram: https://gitdiagram.com/pawafulu7/techtrend
- Repository: https://github.com/pawafulu7/techtrend

## Overview

##### Project Type and Purpose
- This is a full-stack “TechTrend” article aggregator: a Next.js 15 + React 18 frontend, Next.js API routes backend, Prisma-powered PostgreSQL database, Redis cache, and Google Gemini AI summarization. It ingests RSS/HTTP feeds, processes and caches content, generates AI summaries, and serves pages and APIs.

##### Main Components
a. Frontend
- Next.js pages (app/*, components/*)
- React UI components, Tailwind CSS styling
- NextAuth for authentication flows
b. Backend (Next.js API Routes)
- API endpoints under app/api/*
- Business logic libraries in lib/ (fetchers, enrichers, ai, services, cache, recommendation, rag, dataloader)
- Dependency Injection (lib/di)
- Scheduler & Workers (lib/workers) for background embedding jobs, summary regeneration, scheduled feeds
- CLI tools (lib/cli, scripts/)
c. Data Layer
- Prisma ORM → PostgreSQL (prisma/schema.prisma & migrations)
- Redis cache (lib/cache, lib/redis)
d. External Services
- Google Gemini API for AI summarization
- Various RSS and corporate blog endpoints (lib/fetchers, scripts/)
- Email/SMS via Nodemailer
- Observability via OpenTelemetry Collector, Loki, Tempo, Grafana

##### Relationships & Data Flows
- User’s browser ↔ Next.js front (SSR/CSR) → API routes
- API routes call business-logic layers:
- Fetchers → ingest new articles
- Enrichers → normalize content
- AI modules → call Gemini API
- Cache layer → Redis read/write
- Prisma → persistent read/write
- Background workers & scheduler trigger jobs via cron (e.g., feed collection, embedding)
- Observability agents collect traces/logs → OTEL Collector → Loki/Tempo → Grafana

##### Architectural Patterns
- Layered architecture: Presentation (frontend), API/Controller (Next.js routes), Service/Use-Case (lib/services, lib/ai, lib/recommendation), Data (Prisma, Redis)
- Hexagonal/DI: lib/di providers inject Prisma, Redis, scheduler into services
- Caching & Circuit-breaker: lib/cache modules implement layered and distributed caches
- Micro-task workers: lib/workers handle asynchronous jobs

##### Details
- Component names matching file tree: “app/api/articles”, “lib/ai/unified-summary-service”
- Data models via Prisma schema
- Background job queue (embedding-worker.ts)
- Deployment: Docker/Docker-Compose, Vercel, monitoring containers
- Environment variables boundary (env secret store)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Next.js Application"
        subgraph "Frontend Layer"
            Browser["User Browser"]:::external
            Pages["app/page.tsx"]:::frontend
            Layout["app/layout.tsx"]:::frontend
            Globals["app/globals.css"]:::frontend
            Components["app/components/"]:::frontend
            AuthLogin["app/auth/login/page.tsx"]:::frontend
            AuthSignup["app/auth/signup/page.tsx"]:::frontend
            AuthVerify["app/auth/verify/page.tsx"]:::frontend
        end

        subgraph "Backend Layer"
            AuthAPI["app/api/auth/[...nextauth]/route.ts"]:::backend
            APIArticles["app/api/articles"]:::backend
            APIFeedCollect["app/api/feeds/collect/route.ts"]:::backend
            APISummaries["app/api/summaries/generate/route.ts"]:::backend
            Fetchers["lib/fetchers/"]:::service
            Enrichers["lib/enrichers/"]:::service
            AI["lib/ai/"]:::service
            CacheLib["lib/cache/"]:::service
            Services["lib/services/"]:::service
            Recommendation["lib/recommendation/"]:::service
            RAG["lib/rag/"]:::service
            Dataloader["lib/dataloader/"]:::service
            DIbootstrap["lib/di/bootstrap.ts"]:::service
            DIcontainer["lib/di/container.ts"]:::service
            DIproviders["lib/di/providers/"]:::service
            WorkerEmbed["lib/workers/embedding-worker.ts"]:::worker
            WorkerProcessor["lib/workers/job-processor.ts"]:::worker
            ScriptCollect["scripts/scheduled/collect-feeds.ts"]:::worker
            ScriptScheduler["scripts/scheduled/scheduler.ts"]:::worker
            CLIIndex["lib/cli/index.ts"]:::worker
            CLICommands["lib/cli/commands/"]:::worker
            ScriptsDir["scripts/"]:::worker
        end
    end

    Browser -->|"renders SSR/CSR"| Pages
    Pages --> Layout
    Pages --> Components
    Pages --> AuthLogin
    Pages --> AuthSignup
    Pages --> AuthVerify

    Browser -->|"auth request"| AuthAPI
    Browser -->|"API request"| APIArticles
    Browser -->|"API request"| APIFeedCollect
    Browser -->|"API request"| APISummaries

    AuthAPI --> DIcontainer
    APIArticles --> DIcontainer
    APIFeedCollect --> DIcontainer
    APISummaries --> DIcontainer

    DIcontainer --> DIproviders
    DIproviders --> DIbootstrap

    DIcontainer --> Services
    Services --> Fetchers
    Services --> Enrichers
    Services --> AI
    Services --> CacheLib
    Services --> Recommendation
    Services --> RAG
    Services --> Dataloader

    Fetchers -->|"ingest articles"| Feeds
    AI -->|"summarize"| Gemini
    CacheLib --> RedisCache
    Services --> RedisCache
    Services --> Prisma
    DIcontainer --> Prisma
    Prisma --> DBPostgres

    ScriptScheduler --> WorkerEmbed
    ScriptScheduler --> WorkerProcessor
    WorkerEmbed --> AI
    WorkerEmbed --> Services
    WorkerEmbed --> CacheLib
    WorkerEmbed --> Prisma
    WorkerProcessor --> Services

    instrumentation["instrumentation.ts"]:::obs --> OTELCollector
    OTELCollector --> Loki
    OTELCollector --> Tempo
    Loki --> Grafana
    Tempo --> Grafana

    Feeds["External RSS Feeds"]:::external
    Gemini["Google Gemini API"]:::external
    DBPostgres["PostgreSQL"]:::db
    RedisCache["Redis"]:::cache
    OTELCollector["OTEL Collector"]:::obs
    Loki["Loki"]:::obs
    Tempo["Tempo"]:::obs
    Grafana["Grafana"]:::obs

    click Pages "https://github.com/pawafulu7/techtrend/blob/main/app/page.tsx"
    click Layout "https://github.com/pawafulu7/techtrend/blob/main/app/layout.tsx"
    click Globals "https://github.com/pawafulu7/techtrend/blob/main/app/globals.css"
    click Components "https://github.com/pawafulu7/techtrend/tree/main/app/components/"
    click AuthLogin "https://github.com/pawafulu7/techtrend/blob/main/app/auth/login/page.tsx"
    click AuthSignup "https://github.com/pawafulu7/techtrend/blob/main/app/auth/signup/page.tsx"
    click AuthVerify "https://github.com/pawafulu7/techtrend/blob/main/app/auth/verify/page.tsx"
    click AuthAPI "https://github.com/pawafulu7/techtrend/blob/main/app/api/auth/[...nextauth]/route.ts"
    click APIArticles "https://github.com/pawafulu7/techtrend/tree/main/app/api/articles"
    click APIFeedCollect "https://github.com/pawafulu7/techtrend/blob/main/app/api/feeds/collect/route.ts"
    click APISummaries "https://github.com/pawafulu7/techtrend/blob/main/app/api/summaries/generate/route.ts"
    click Fetchers "https://github.com/pawafulu7/techtrend/tree/main/lib/fetchers/"
    click Enrichers "https://github.com/pawafulu7/techtrend/tree/main/lib/enrichers/"
    click AI "https://github.com/pawafulu7/techtrend/tree/main/lib/ai/"
    click CacheLib "https://github.com/pawafulu7/techtrend/tree/main/lib/cache/"
    click Services "https://github.com/pawafulu7/techtrend/tree/main/lib/services/"
    click Recommendation "https://github.com/pawafulu7/techtrend/tree/main/lib/recommendation/"
    click RAG "https://github.com/pawafulu7/techtrend/tree/main/lib/rag/"
    click Dataloader "https://github.com/pawafulu7/techtrend/tree/main/lib/dataloader/"
    click DIbootstrap "https://github.com/pawafulu7/techtrend/blob/main/lib/di/bootstrap.ts"
    click DIcontainer "https://github.com/pawafulu7/techtrend/blob/main/lib/di/container.ts"
    click DIproviders "https://github.com/pawafulu7/techtrend/tree/main/lib/di/providers/"
    click WorkerEmbed "https://github.com/pawafulu7/techtrend/blob/main/lib/workers/embedding-worker.ts"
    click WorkerProcessor "https://github.com/pawafulu7/techtrend/blob/main/lib/workers/job-processor.ts"
    click ScriptCollect "https://github.com/pawafulu7/techtrend/blob/main/scripts/scheduled/collect-feeds.ts"
    click ScriptScheduler "https://github.com/pawafulu7/techtrend/blob/main/scripts/scheduled/scheduler.ts"
    click CLIIndex "https://github.com/pawafulu7/techtrend/blob/main/lib/cli/index.ts"
    click CLICommands "https://github.com/pawafulu7/techtrend/tree/main/lib/cli/commands/"
    click ScriptsDir "https://github.com/pawafulu7/techtrend/tree/main/scripts/"
    click DBPostgres "https://github.com/pawafulu7/techtrend/blob/main/prisma/schema.prisma"
    click DBPostgres "https://github.com/pawafulu7/techtrend/tree/main/prisma/migrations/"
    click RedisCache "https://github.com/pawafulu7/techtrend/blob/main/lib/redis/client.ts"
    click RedisCache "https://github.com/pawafulu7/techtrend/blob/main/lib/redis/redis-service.ts"
    click CacheLib "https://github.com/pawafulu7/techtrend/blob/main/lib/cache/redis-cache.ts"
    click Gemini "https://github.com/pawafulu7/techtrend/blob/main/lib/ai/adapter/gemini-summary-adapter.ts"
    click Gemini "https://github.com/pawafulu7/techtrend/blob/main/lib/ai/gemini.ts"
    click Gemini "https://github.com/pawafulu7/techtrend/blob/main/lib/ai/transport/gemini-transport.ts"
    click instrumentation "https://github.com/pawafulu7/techtrend/blob/main/instrumentation.ts"
    click OTELCollector "https://github.com/pawafulu7/techtrend/blob/main/otel-collector-config.yaml"
    click OTELCollector "https://github.com/pawafulu7/techtrend/blob/main/loki-config.yaml"
    click Grafana "https://github.com/pawafulu7/techtrend/blob/main/docker-compose.monitoring.yml"

    classDef frontend fill:#AEDFF7,stroke:#000
    classDef backend fill:#C6F7C3,stroke:#000
    classDef service fill:#D5D5D5,stroke:#000
    classDef worker fill:#F0E68C,stroke:#000
    classDef db fill:#F5B041,stroke:#000
    classDef cache fill:#BB8FCE,stroke:#000
    classDef external fill:#F1948A,stroke:#000
    classDef obs fill:#85C1E9,stroke:#000
```
