# quinsberry/rst-recrutment-task architecture

> Architecture diagram of the GitHub repository quinsberry/rst-recrutment-task, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quinsberry/rst-recrutment-task
- Repository: https://github.com/quinsberry/rst-recrutment-task

## Overview

##### Project Type and Purpose
- The project is a full-stack application built with Next.js. Its primary purpose is to manage users and their addresses with CRUD operations. It leverages server-side validations and modular components to allow extension to additional CRUD modules in the future.
- The README explicitly details a feature-based architecture, a PostgreSQL database with Prisma ORM, and deployment via Docker.

##### Directories and Components
a. Application Layers and Directories:
- "src/app": Contains the Next.js app router pages, including API endpoints (e.g., src/app/api/addresses/route.ts) used for server-side operations.
- "src/entities": Hosts domain entities (e.g., user, address) which encapsulate business logic and data interactions. Within each entity, you see further partitioning for API actions, the model, and UI components.
- "src/features": Contains feature modules such as "user-addresses-list" and "users-list", allowing separation of concerns around specific functionalities. This is where you see actions (like add, edit, delete) and associated UI/dialog components.
- "src/shared": Provides shared UI components (buttons, dialogs, pagination, etc.), libraries (for DB and utils), hooks, and styles that standardize the experience across features and entities.
- "src/widgets": Contains complex, composite UI components that integrate functionality across entities and features, supporting more advanced flows.

b. Infrastructure & Configuration:
- “prisma” directory: Holds the Prisma schema (schema.prisma) which defines the PostgreSQL database structure, while the build folder includes sample data initialization through init.sql.
- Docker related files (Dockerfile, docker-compose.yml, and docker-compose.prod.yml) show that containerization and deployment orchestration are integral to the project.
- Configuration files (.env.example, next.config.ts, tsconfig.json) and build tools (eslint.config.mjs, postcss.config.mjs) indicate careful configuration of both development and production environments.

##### Main Components and Their Relationships
- Frontend/UI: Composed of Next.js pages (layout.tsx, page.tsx in src/app), UI components from entities, features, shared, and widgets. The UI is designed to show paginated lists and modals for real-time address preview and CRUD operations.
- API Layer: Next.js Server Actions (visible in directories under src/app/api and the API submodules within each entity) that handle database operations and act as the bridge between client-side interactions and database updates.
- Domain Logic: Entities (for users and addresses) contain modules for API actions, models, and UI elements that encapsulate business rules.
- Data Persistence: The PostgreSQL database, with its schema defined in Prisma. Data handling and migrations are managed via Prisma commands and Docker deployments.
- Deployment and DevOps: Docker and Docker Compose are used for containerizing the application and configuring both local and production environments.

##### Architectural Patterns and Design Principles
- Feature-Based Modular Architecture: The project is split into “entities,” “features,” “shared,” and “widgets” which encourages encapsulation, reusability, and scalability.
- Separation of Concerns: Clear separation between presentation (UI), business logic (entities), and data access (API/Prisma/Database).
- Extensibility: The design anticipates similar modules (like “users_tasks” etc.) by keeping patterns generic and modular.
- Containerization: Use of Docker to ensure consistency between development and production environments.

- Use clear labels for:
- "Next.js App Layer (src/app)" with its API endpoints.
- "Domain Entities" (users and addresses).
- "Feature Modules" (user-addresses-list, users-list).
- "Shared Components" and "Widgets" for composable UI elements.
- "PostgreSQL Database" connected via "Prisma ORM".
- "Docker/Deployment" concepts alongside environment setups.
- Optionally, include notes or side annotations that highlight important technical decisions such as server-side rendering, real-time data validations, and modular design principles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/UI Layer"
        direction TB
        NextJsPages["Next.js Pages (layout.tsx, page.tsx)"]:::frontend
        FeatureUserAdd["Feature: User Addresses Management"]:::frontend
        FeatureUsersList["Feature: Users List Management"]:::frontend
        SharedComponents["Shared Components & Utilities"]:::frontend
        Widgets["Widgets (Composite UI Components)"]:::frontend
    end

    subgraph "API & Business Logic Layer"
        direction TB
        ApiEndpoints["Next.js API Endpoints (addresses)"]:::api
        subgraph "Domain Entities"
            direction TB
            AddressEntity["Address Entity (Business Logic)"]:::domain
            UserEntity["User Entity (Business Logic)"]:::domain
        end
    end

    subgraph "Data Persistence & Infrastructure"
        direction TB
        Database["PostgreSQL Database (via Prisma ORM)"]:::db
        Docker["Docker & DevOps (Containerized Deployment)"]:::infra
    end

    NextJsPages -->|"triggers"| ApiEndpoints
    ApiEndpoints -->|"processes"| AddressEntity
    ApiEndpoints -->|"processes"| UserEntity
    AddressEntity -->|"DB operations"| Database
    UserEntity -->|"DB operations"| Database

    FeatureUserAdd -->|"integrates"| NextJsPages
    FeatureUsersList -->|"integrates"| NextJsPages
    SharedComponents -->|"supports"| NextJsPages
    Widgets -->|"supports"| NextJsPages

    Docker --- NextJsPages
    Docker --- ApiEndpoints
    Docker --- Database

    click NextJsPages "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/app"
    click ApiEndpoints "https://github.com/quinsberry/rst-recrutment-task/blob/main/src/app/api/addresses/route.ts"
    click AddressEntity "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/entities/address"
    click UserEntity "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/entities/user"
    click FeatureUserAdd "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/features/user-addresses-list"
    click FeatureUsersList "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/features/users-list"
    click SharedComponents "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/shared"
    click Widgets "https://github.com/quinsberry/rst-recrutment-task/tree/main/src/widgets/users-addresses"
    click Database "https://github.com/quinsberry/rst-recrutment-task/tree/main/prisma"
    click Docker "https://github.com/quinsberry/rst-recrutment-task/tree/main/Dockerfile"

    classDef frontend fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef domain fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef db fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef infra fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
```
