# tranvelocity/social-api architecture

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

- Interactive diagram: https://gitdiagram.com/tranvelocity/social-api
- Repository: https://github.com/tranvelocity/social-api

## Overview

##### Project type and purpose
- This is a full-stack, backend-only RESTful API built on Laravel 10. It exposes social features (users, posts, comments, likes, media, roles, sessions, etc.) through a clean, modular architecture.
- Docker Compose manages local development containers (app, database, possibly Swagger UI), and modules encapsulate each feature for easy extension.

##### File structure
- Top-level:
- Dockerfile, docker-compose.yml, nginx/ – define runtime containers (PHP-FPM, MySQL, Nginx reverse proxy).
- src/ – Laravel app, subdivided into app/, config/, database/, public/, plus Modules/ where each feature (User, Post, Comment, etc.) lives.
- docs/api/ – OpenAPI spec and static HTML generator script.
- .github/workflows – CI/CD pipelines (test, deploy).
- Each Module follows the same pattern: app/ (Controllers, Models, Services, Repositories, Providers), config/, database/, routes/, composer.json, module.json.

##### README for additional insights
- It explicitly calls out a “modular” design using nwidart/laravel-modules.
- Dependencies: Laravel 10, Docker, Swagger/OpenAPI, PHPUnit, PHPStan.
- Goals: scalability, modularity, automated testing, containerized local dev.

##### Main components
a. External Clients
- Mobile apps, Web apps, CLI tools consuming the API.
b. Edge / API Gateway
- Nginx container (nginx/conf/app.conf).
- Docker Compose network front-ends all HTTP requests to PHP-FPM.
c. Application Container
- PHP-FPM running Laravel code.
- Core module (src/Modules/Core) responsible for routing, exception handling, middleware (authentication, logging).
- Feature modules: User, Member, Post, Comment, Like, Media, Admin, AuditLog, Cache, Notification (Slack), PingPong, Session, ThrottleConfig, RestrictedUser, Role, etc.
d. Data stores
- MySQL container (configured in docker-compose.yml and config/database.php).
- Modules enforce table migrations and seeders in each module’s database/ directory.
e. External Services
- AWS S3 (src/Modules/AWS/S3) for file storage.
- Slack (src/Modules/Notification/Slack) for notifications.
- Logging targets (DataDog, NewRelic) configured in Core/Logging.
f. Documentation & CI/CD
- docs/api/api.yaml → Swagger UI (separate container or URL).
- .github/workflows → GitHub Actions pipelines for test and deploy.

##### Relationships and interactions
- Clients → (HTTPS) → Nginx → PHP-FPM (Laravel) → Router → Module Controllers → Services → Repositories → MySQL.
- Certain Services (AWS FileService, SlackNotification, CacheRepository) interact with external AWS S3, Slack API, or Redis/cache store.
- Core middleware components handle authentication (Session, API signature), throttling (ThrottleConfig), and error transformation.

##### Architectural patterns and design principles
- Modular monolith: each feature is its own module with independent routes, services, providers.
- Dependency Inversion: Controllers depend on interface abstractions (RepositoryInterface) injected by Service Providers.
- Repository and Service layers separate persistence from business logic.
- Middleware pipeline for cross-cutting concerns (authentication, rate limiting).
- Single entrypoint pattern: public/index.php → bootstrap/app.php → modules loaded via nwidart/laravel-modules.

1. Clients
2. Nginx container
3. PHP-FPM container with nested module groups
4. MySQL container
5. (Optional) Redis container if used for cache
6. External AWS S3
7. External Slack API
8. CI/CD pipelines
9. Swagger UI container or URL
- “HTTP Request”, “DB Query”, “S3 Upload”, “Slack Notification”.

##### Final advice
Be comprehensive but avoid clutter. Each module’s internal components need not be fully decomposed; group them logically. Focus on data flow, service interactions, and module boundaries to convey the modular-monolith architecture clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Local Environment"
        DockerCompose["Docker Compose (Local Dev Containers)"]:::container
        Dockerfile["Dockerfile (PHP-FPM Container Definition)"]:::container
        Nginx["Nginx (API Gateway)"]:::container
        PHP_FPM["PHP-FPM (Laravel Application)"]:::container
        MySQL["MySQL"]:::datastore
        Redis["Redis (Cache)"]:::datastore
        SwaggerUI["Swagger UI"]:::container
    end

    Clients["External Clients (Mobile/Web/CLI)"]:::external

    PHP_FPM -->|DB Query| MySQL
    PHP_FPM -->|Cache Query| Redis

    Clients -->|HTTP Request| Nginx
    Nginx -->|Forward HTTP| PHP_FPM
    PHP_FPM -->|Serve Docs| SwaggerUI

    subgraph "Laravel Application (Modules)" 
        Core["Core Module"]:::module
        User["User Module"]:::module
        Member["Member Module"]:::module
        Post["Post Module"]:::module
        Comment["Comment Module"]:::module
        Like["Like Module"]:::module
        Media["Media Module"]:::module
        Admin["Admin Module"]:::module
        AuditLog["AuditLog Module"]:::module
        Cache["Cache Module"]:::module
        Notification["Notification Module"]:::module
        AWS_S3["AWS S3 Module"]:::module
        PingPong["PingPong Module"]:::module
        Session["Session Module"]:::module
        ThrottleConfig["ThrottleConfig Module"]:::module
        RestrictedUser["RestrictedUser Module"]:::module
        Role["Role Module"]:::module
    end

    PHP_FPM -->|Load Modules| Core
    Core --> User
    Core --> Member
    Core --> Post
    Core --> Comment
    Core --> Like
    Core --> Media
    Core --> Admin
    Core --> AuditLog
    Core --> Cache
    Core --> Notification
    Core --> AWS_S3
    Core --> PingPong
    Core --> Session
    Core --> ThrottleConfig
    Core --> RestrictedUser
    Core --> Role

    Media -->|S3 Upload| AWS_S3
    Notification -->|Send Notification| SlackAPI["Slack API"]:::external

    subgraph "CI/CD Pipeline"
        TestCI["Test Workflow"]:::pipeline
        DeployCI["Deploy Workflow"]:::pipeline
        DocsScript["API Doc Generator Script"]:::pipeline
        ModuleMaker["Module Maker Script"]:::pipeline
    end

    TestCI -->|Generates| DocsScript
    DocsScript -->|Updates| SwaggerUI
    TestCI --> ModuleMaker
    DeployCI -->|Deploys Containers| DockerCompose

    classDef container fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef module fill:#DFFFE0,stroke:#28a745,stroke-width:1px;
    classDef external fill:#FFE4B2,stroke:#ff8c00,stroke-width:1px;
    classDef datastore fill:#EDEDED,stroke:#6a737d,stroke-width:1px;
    classDef pipeline fill:#F0DFFF,stroke:#6f42c1,stroke-width:1px;

    click Nginx "https://github.com/tranvelocity/social-api/blob/master/nginx/conf/app.conf"
    click DockerCompose "https://github.com/tranvelocity/social-api/blob/master/docker-compose.yml"
    click Dockerfile "https://github.com/tranvelocity/social-api/tree/master/Dockerfile"
    click PHP_FPM "https://github.com/tranvelocity/social-api/tree/master/src/"
    click Core "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Core"
    click User "https://github.com/tranvelocity/social-api/tree/master/src/Modules/User"
    click Member "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Member"
    click Post "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Post"
    click Comment "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Comment"
    click Like "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Like"
    click Media "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Media"
    click Admin "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Admin"
    click AuditLog "https://github.com/tranvelocity/social-api/tree/master/src/Modules/AuditLog"
    click Cache "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Cache"
    click Notification "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Notification"
    click AWS_S3 "https://github.com/tranvelocity/social-api/tree/master/src/Modules/AWS/S3"
    click PingPong "https://github.com/tranvelocity/social-api/tree/master/src/Modules/PingPong"
    click Session "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Session"
    click ThrottleConfig "https://github.com/tranvelocity/social-api/tree/master/src/Modules/ThrottleConfig"
    click RestrictedUser "https://github.com/tranvelocity/social-api/tree/master/src/Modules/RestrictedUser"
    click Role "https://github.com/tranvelocity/social-api/tree/master/src/Modules/Role"
    click MySQL "https://github.com/tranvelocity/social-api/blob/master/docker-compose.yml"
    click DocsScript "https://github.com/tranvelocity/social-api/blob/master/scripts/api_doc_generator.sh"
    click ModuleMaker "https://github.com/tranvelocity/social-api/blob/master/scripts/module_maker.sh"
    click TestCI "https://github.com/tranvelocity/social-api/blob/master/.github/workflows/test.yml"
    click DeployCI "https://github.com/tranvelocity/social-api/blob/master/.github/workflows/deploy.yml"
```
