# karadyaur/soul-connect architecture

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

- Interactive diagram: https://gitdiagram.com/karadyaur/soul-connect
- Repository: https://github.com/karadyaur/soul-connect

## Overview

##### Main Components
- API Gateway (sc-api-getaway): Acts as the front door for client requests. It routes incoming requests to other microservices, and its configuration files (e.g., Dockerfile, nginx/nginx.conf) indicate that it may use Nginx as a reverse proxy.
- Microservices:
- Auth Service (sc-auth): Handles authentication, user sessions, and related security. Contains SQL migrations and DB query files using tools like sqlc.
- User Service (sc-user): Manages user data and profiles with its own database migrations and queries.
- Post Service (sc-post): Manages posts, including operations for posting content, likes, comments, labels, and uses dedicated database schemas.
- Notification Service (sc-notification): Processes notifications, complete with its own SQL migration and query setups.
- Kafka Service (sc-kafka): Integrates Kafka for asynchronous communication; includes both producer and consumer patterns to support event-driven interactions among services.
- Frontend Client (sc-webapp): A web application (likely built using React and TypeScript, as indicated by .tsx files) that interacts with the backend via the API Gateway.
- Database: The “postgres” directory indicates that PostgreSQL is used. Each service (auth, user, post, notification) appears to handle its own schema and migrations, suggesting either separate schemas or databases per microservice.
- Inter-service Communication: The presence of a “proto” directory with a gRPC definition (auth.proto) suggests that some services communicate using gRPC, enhancing performance and type-safety in service interactions.

##### Relationships and Interactions
- The Frontend (sc-webapp) sends HTTP requests to the API Gateway, which then dispatches these requests to the appropriate microservices.
- The API Gateway may perform load balancing, authentication checks, and then route requests to services such as Auth, User, Post, or Notification.
- Internal microservices may interact synchronously (using REST or gRPC) for direct communication or asynchronously via Kafka for event-driven updates (managed by the sc-kafka service).
- Each microservice connects to its respective PostgreSQL database (or schema) for persistence.
- Docker-Compose and additional docker files (docker-compose.yml, local.docker-compose.yml) orchestrate the running of all containers as a unified system.

##### Architectural Patterns and Design Principles
- Microservices Architecture: The project clearly separates concerns by using individual services for authentication, user management, posts, notifications, and asynchronous processing with Kafka.
- API Gateway Pattern: Centralizes external communication to control routing, security, and load distribution.
- Containerization and Orchestration: Docker files and docker-compose configurations ensure that the environment is reproducible and scalable.
- Use of gRPC: Enhances strong-typed communication between services (as seen via proto definitions).
- SQL Migration and Query Generation: Use of tools such as sqlc enforces a strict data layer separation in each service.

##### Emphasizing Detail
- That every microservice’s connection to its data store is shown because the file structure emphasizes SQL migrations and queries.
- Interplay between synchronous (API calls and gRPC) and asynchronous (Kafka-driven events) communications.
- That the system design should incorporate scalability (e.g., stateless services behind load balancers) which is supported by containerization and the separate microservices approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend Client (sc-webapp)"]:::frontend
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        GW["API Gateway (sc-api-getaway)"]:::gateway
    end

    %% Microservices Layer
    subgraph "Microservices Layer"
        AUTH["Auth Service (sc-auth)"]:::service
        USER["User Service (sc-user)"]:::service
        POST["Post Service (sc-post)"]:::service
        NOTIF["Notification Service (sc-notification)"]:::service
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DB["PostgreSQL Database (postgres)"]:::db
        RPC["gRPC (proto/auth.proto)"]:::rpc
        KAFKA["Kafka Service (sc-kafka)"]:::kafka
    end

    %% Connections between layers
    FE -->|"HTTP"| GW
    GW -->|"Routes"| AUTH
    GW -->|"Routes"| USER
    GW -->|"Routes"| POST
    GW -->|"Routes"| NOTIF

    %% Microservices to Database connections
    AUTH -->|"CRUD"| DB
    USER -->|"CRUD"| DB
    POST -->|"CRUD"| DB
    NOTIF -->|"CRUD"| DB

    %% Microservices using gRPC
    AUTH -->|"gRPC"| RPC
    USER -->|"gRPC"| RPC
    POST -->|"gRPC"| RPC
    NOTIF -->|"gRPC"| RPC

    %% Asynchronous communication with Kafka
    AUTH -->|"async"| KAFKA
    USER -->|"async"| KAFKA
    POST -->|"async"| KAFKA
    NOTIF -->|"async"| KAFKA

    KAFKA -->|"events"| AUTH
    KAFKA -->|"events"| USER
    KAFKA -->|"events"| POST
    KAFKA -->|"events"| NOTIF

    %% Click Events
    click FE "https://github.com/karadyaur/soul-connect/tree/main/sc-webapp/"
    click GW "https://github.com/karadyaur/soul-connect/tree/main/sc-api-getaway/"
    click AUTH "https://github.com/karadyaur/soul-connect/tree/main/sc-auth/"
    click USER "https://github.com/karadyaur/soul-connect/tree/main/sc-user/"
    click POST "https://github.com/karadyaur/soul-connect/tree/main/sc-post/"
    click NOTIF "https://github.com/karadyaur/soul-connect/tree/main/sc-notification/"
    click KAFKA "https://github.com/karadyaur/soul-connect/tree/main/sc-kafka/"
    click DB "https://github.com/karadyaur/soul-connect/tree/main/postgres/"
    click RPC "https://github.com/karadyaur/soul-connect/tree/main/proto/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef gateway fill:#D8BFD8,stroke:#333,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef db fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef kafka fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef rpc fill:#FFDEAD,stroke:#333,stroke-width:2px;
```
