How tranvelocity/social-api works
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.