# yukionishi1129/techpicks architecture

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

- Interactive diagram: https://gitdiagram.com/yukionishi1129/techpicks
- Repository: https://github.com/yukionishi1129/techpicks

## Overview

##### Project type and purpose
- This is a full-stack, microservice-based monorepo for “Check Picks.”
- It comprises multiple frontend applications (web client v1, web client v2, admin panel, React Native mobile stub), a GraphQL BFF (Apollo Gateway), several Go-based gRPC microservices, batch jobs, and a Supabase (PostgreSQL) database.

##### File structure
- Top-level directories:
- web/client-v2, web/admin, web/client – Next.js frontends
- mobile/rn-client – React Native mobile app
- bff/apollo-gateway – NestJS GraphQL gateway
- micro-service/… – content-service, bookmark-service, favorite-service, my-feed-service, user-service (Go + gRPC)
- batch-service – Go batch jobs (crawlers, seed/migrations, trend crawlers)
- supabase – DB migrations & config
- Each microservice follows a clean architecture: internal/application, internal/adapter, internal/domain, infrastructure, interfaces (handlers).
- Configuration/build files: Dockerfiles, cloudbuild.yaml, Makefiles, .env.sample.

##### Key README insights
- Frontends use Next.js, TypeScript, Apollo Client, supabase-js, Tailwind.
- BFF uses NestJS + Apollo Server to stitch GraphQL schemas, delegates resolvers to underlying gRPC services.
- Microservices are Go binaries with gRPC servers, using SQLBoiler for ORM, deployed to Cloud Run.
- batch-service runs as Cloud Run Jobs for periodic crawls (RSS, 3rd-party APIs) and Firestore seeding.

##### Main components
a. Frontends (Client-v2, Admin, optional Mobile)
b. BFF / GraphQL Gateway
c. Microservices (gRPC servers):
– Content Service
– Bookmark Service
– My-Feed Service
– Favorite Service
– User Service
d. Batch Processing Jobs (batch-service)
e. Database layer: Supabase (PostgreSQL)
f. External APIs & data sources: RSS feeds, OGP, 3rd-party article APIs
g. CI/CD pipelines & infrastructure (Cloud Run, Cloud Build)

##### Relationships and interactions
- User browser/mobile → HTTP/HTTPS → Next.js frontend
- Next.js → GraphQL over HTTP → Apollo Gateway
- Apollo Gateway → gRPC → Microservices
- Microservices → SQLBoiler → Supabase (PostgreSQL)
- Batch-service jobs → external APIs (RSS, site crawlers) → Firestore or Supabase
- Microservices may call each other via gRPC or via Gateway
- External authentication via Supabase auth or JWT

##### Architectural patterns & design principles
- Microservices with clear domain boundaries, gRPC for inter-service comms
- GraphQL gateway for unified API endpoint and schema stitching
- Clean architecture within Go services (ports & adapters)
- Next.js ISR/SSR frontends decoupled from backend
- Batch jobs decoupled from real-time services

##### Final checklist
- Components: Frontends, Gateway, Microservices, Batch Jobs, Database, External APIs
- Interactions: HTTP, GraphQL, gRPC, ORM calls, external API pulls
- Labels: component name + protocol/tech (e.g., “Bookmark Service – gRPC”)
- Deployment boundaries: Cloud Run, Supabase, local/dev

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD & Infra
    subgraph "CI/CD & Infra"
        direction TB
        CI["CI/CD Workflows"]:::infra
    end

    %% Developer Frontends
    subgraph "Developer Frontends"
        direction TB
        WCv2["Web Client v2"]:::frontend
        WCv1["Web Client v1"]:::frontend
        Admin["Admin Panel"]:::frontend
        Mobile["Mobile App (RN)"]:::frontend
    end

    %% API Layer
    Gateway["Apollo GraphQL Gateway"]:::api

    %% Cloud Run Services
    subgraph "Cloud Run Services"
        direction TB
        subgraph "gRPC Microservices"
            direction TB
            Content["Content Service"]:::service
            Bookmark["Bookmark Service"]:::service
            Favorite["Favorite Service"]:::service
            MyFeed["My-Feed Service"]:::service
            UserService["User Service"]:::service
        end
        Batch["Batch Processing Jobs"]:::batch
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Supabase["Supabase (PostgreSQL)"]:::database
    end

    %% External Systems
    subgraph "External APIs & Data Sources"
        direction TB
        ExtAPIs["RSS / OGP / 3rd-party APIs"]:::external
    end

    %% Connections
    CI --> WCv2
    CI --> WCv1
    CI --> Admin
    CI --> Mobile
    CI --> Gateway

    WCv2 -->|HTTP/GraphQL| Gateway
    WCv1 -->|HTTP/GraphQL| Gateway
    Admin -->|HTTP/GraphQL| Gateway
    Mobile -->|HTTP/GraphQL| Gateway

    Gateway -->|gRPC| Content
    Gateway -->|gRPC| Bookmark
    Gateway -->|gRPC| Favorite
    Gateway -->|gRPC| MyFeed
    Gateway -->|gRPC| UserService

    Content -->|SQL| Supabase
    Bookmark -->|SQL| Supabase
    Favorite -->|SQL| Supabase
    MyFeed -->|SQL| Supabase
    UserService -->|SQL| Supabase

    Batch -->|fetch| ExtAPIs
    ExtAPIs -->|data| Batch
    Batch -->|SQL| Supabase

    %% Click Events
    click WCv2 "https://github.com/yukionishi1129/techpicks/tree/develop/web/client-v2"
    click WCv1 "https://github.com/yukionishi1129/techpicks/tree/develop/web/client"
    click Admin "https://github.com/yukionishi1129/techpicks/tree/develop/web/admin"
    click Mobile "https://github.com/yukionishi1129/techpicks/tree/develop/mobile/rn-client"
    click Gateway "https://github.com/yukionishi1129/techpicks/tree/develop/bff/apollo-gateway"
    click Content "https://github.com/yukionishi1129/techpicks/tree/develop/micro-service/content-service"
    click Bookmark "https://github.com/yukionishi1129/techpicks/tree/develop/micro-service/bookmark-service"
    click Favorite "https://github.com/yukionishi1129/techpicks/tree/develop/micro-service/favorite-service"
    click MyFeed "https://github.com/yukionishi1129/techpicks/tree/develop/micro-service/my-feed-service"
    click UserService "https://github.com/yukionishi1129/techpicks/tree/develop/micro-service/user-service"
    click Batch "https://github.com/yukionishi1129/techpicks/tree/develop/batch-service"
    click Supabase "https://github.com/yukionishi1129/techpicks/tree/develop/supabase"
    click CI "https://github.com/yukionishi1129/techpicks/blob/develop/cloudbuild.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef api fill:#FFEBCC,stroke:#D97706,stroke-width:1px
    classDef service fill:#DFFFE0,stroke:#15803D,stroke-width:1px
    classDef batch fill:#FFF4D6,stroke:#D69E2E,stroke-width:1px
    classDef database fill:#FFE0E6,stroke:#B91C1C,stroke-width:1px
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:1px
    classDef infra fill:#F4F4F5,stroke:#9CA3AF,stroke-width:1px
```
