# 0xboji/note-sol-core architecture

> Architecture diagram of the GitHub repository 0xboji/note-sol-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xboji/note-sol-core
- Repository: https://github.com/0xboji/note-sol-core

## Overview

##### Main Components
- API Entry Point: Start with the main bootstrapping in cmd/api/main.go. This is where the server is started and routes are registered.
- Router & Handlers: The REST endpoints are defined in multiple locations:
- The api/v1/handlers directory (e.g., user_handler.go) and the routes directory (routes/routes.go) indicate the endpoints and associated request routing.
- Additional handler logic is also found in the handlers and internal/users directories.
- Service Layer: There are clear service components:
- In api/v1/services (user_service.go)
- Also in internal/services and internal/users/service.go, handling business logic.
- Repository Layer: This is where data persistence is managed:
- The internal/repositories directory (with a base repository and user_repository.go) abstracts database operations.
- The pkg/config/database.go shows how the database (PostgreSQL) is configured.
- Domain & Models:
- internal/domain and models directories contain business entities (e.g., user.go, post.go) and migration definitions.
- Authentication & Middleware:
- The internal/auth and internal/middleware directories indicate usage of JWT and request filtering.
- Additional Components:
- Wallet functionality in internal/wallet/solana.go suggests integration with external services or blockchain functions.
- Migrations folder provides SQL scripts to set up the database schema.

##### Relationships and Interactions
- Client requests hit the API endpoint (via the bootstrapping in cmd/api/main.go), then get routed by routes/routes.go.
- Requests are handled by the appropriate handler (e.g., user_handler.go in api/v1/handlers or internal/users/handler.go) which then calls the respective service layer.
- The service layer contains business logic and interacts with the repository layer to fetch or update data in the PostgreSQL database.
- Middleware (authentication) intercepts requests (found in internal/middleware/auth.go) to perform tasks like JWT verification before reaching handlers.
- External configuration (pkg/config/database.go) is used to establish the database connection, and database migrations initialize the database schema.

##### Architectural Patterns & Principles
- Layered Architecture: There is a clear separation between the API layer, business logic (services), data layer (repositories/models), and configuration/infrastructure.
- Modular Design: The existence of versioned API endpoints (api/v1) and separate components for authentication, middleware, and external integrations (wallet) emphasizes an extensible, maintainable architecture.
- Separation of Concerns: Handlers manage HTTP level interactions, services perform business logic, and repositories handle database interactions.
- Infrastructure as Code: Use of migrations and environment configuration emphasizes a robust deployment pipeline for database provisioning and service start-up.

##### Relevant Technologies
- Go & Gin for the web framework.
- PostgreSQL (or Supabase) for database operations.
- Swagger (via swag) for API documentation.
- JWT for authentication.
- If applicable, integration with blockchain services (Solana).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entry
    Client["Client Request"]:::external
    Client --> mainEntry

    %% API Layer
    subgraph "API Layer"
        mainEntry["API Entry Point"]:::api
        routes["Routes (routes/routes.go)"]:::api
        authMiddleware["Auth Middleware"]:::middleware
        jwtAuth["JWT Authentication"]:::middleware
        userHandler["User Handler"]:::api
        postHandler["Post Handler"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        userServiceV1["User Service (v1)"]:::service
        userServiceInternal["User Service (internal)"]:::service
    end

    %% Repository Layer
    subgraph "Repository Layer"
        baseRepo["Base Repository"]:::repository
        userRepo["User Repository"]:::repository
    end

    %% Domain & Models
    subgraph "Domain & Models"
        domainEntity["Domain Entity"]:::domain
        dbModel["Database Model"]:::domain
    end

    %% Database & Infrastructure
    subgraph "Database & Infrastructure"
        dbConfig["Database Configuration"]:::infra
        migrations["Migrations"]:::infra
    end

    %% External Integration
    subgraph "External Integration"
        solanaIntegration["Solana Integration"]:::external
        solanaBlockchain["Solana Blockchain"]:::external
    end

    %% Connections within API Layer
    mainEntry --> routes
    routes --> authMiddleware
    authMiddleware -- "uses" --> jwtAuth
    authMiddleware --> userHandler
    authMiddleware --> postHandler

    %% Connections from API Layer to Service Layer
    userHandler --> userServiceV1
    userHandler --> userServiceInternal

    %% Connections from Service Layer to Repository Layer
    userServiceV1 --> baseRepo
    userServiceInternal --> userRepo

    %% Connections from Repository Layer to Database & Infrastructure
    baseRepo --> dbConfig
    userRepo --> dbConfig
    dbConfig --> migrations

    %% Connections to Domain & Models
    baseRepo --- domainEntity
    userRepo --- dbModel
    domainEntity --- dbModel

    %% External Integration connection
    userServiceInternal --> solanaIntegration
    solanaIntegration --> solanaBlockchain

    %% Click Events
    click mainEntry "https://github.com/0xboji/note-sol-core/blob/main/cmd/api/main.go"
    click routes "https://github.com/0xboji/note-sol-core/blob/main/routes/routes.go"
    click userHandler "https://github.com/0xboji/note-sol-core/blob/main/api/v1/handlers/user_handler.go"
    click postHandler "https://github.com/0xboji/note-sol-core/blob/main/handlers/post_handler.go"
    click userServiceV1 "https://github.com/0xboji/note-sol-core/blob/main/api/v1/services/user_service.go"
    click userServiceInternal "https://github.com/0xboji/note-sol-core/blob/main/internal/services/user_service.go"
    click baseRepo "https://github.com/0xboji/note-sol-core/blob/main/internal/repositories/base.go"
    click userRepo "https://github.com/0xboji/note-sol-core/blob/main/internal/repositories/user_repository.go"
    click domainEntity "https://github.com/0xboji/note-sol-core/blob/main/internal/domain/user.go"
    click dbModel "https://github.com/0xboji/note-sol-core/blob/main/internal/models/user.go"
    click jwtAuth "https://github.com/0xboji/note-sol-core/blob/main/internal/auth/jwt.go"
    click authMiddleware "https://github.com/0xboji/note-sol-core/blob/main/internal/middleware/auth.go"
    click dbConfig "https://github.com/0xboji/note-sol-core/blob/main/pkg/config/database.go"
    click migrations "https://github.com/0xboji/note-sol-core/blob/main/migrations/000001_create_users_table.up.sql"
    click solanaIntegration "https://github.com/0xboji/note-sol-core/blob/main/internal/wallet/solana.go"

    %% Styles
    classDef api fill:#A8D9FF,stroke:#333,stroke-width:2px;
    classDef service fill:#FFDB99,stroke:#333,stroke-width:2px;
    classDef repository fill:#C2F0C2,stroke:#333,stroke-width:2px;
    classDef domain fill:#F0C2F0,stroke:#333,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef middleware fill:#FFFFB3,stroke:#333,stroke-width:2px;
    classDef external fill:#FAD2E1,stroke:#333,stroke-width:2px;
```
