# renzomedina/realestate-api architecture

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

- Interactive diagram: https://gitdiagram.com/renzomedina/realestate-api
- Repository: https://github.com/renzomedina/realestate-api

## Overview

##### Project type and purpose
- This is a standalone, monolithic RESTful API (no bundled frontend) whose sole responsibility is exposing CRUD operations for real estate properties.
- Built with FastAPI (Python), it handles authentication via JWT, validates payloads with Pydantic, persists data in a relational database, and auto-documents endpoints with OpenAPI/Swagger. It’s containerized and uses GitHub Actions for CI/CD.

##### File structure
- Top-level CI config:
- .github/workflows/api-ci.yml → GitHub Actions pipeline (lint, test, build, push)
- App code:
- src/app.js  (entry point for the FastAPI server – despite “.js”, README indicates Python; treat as the main application module)
- Tests:
- test/app.test.js → Pytest or Jest tests for endpoint coverage
- Package management:
- package.json / package-lock.json → dependencies, scripts (start, test, dockerize)
- Missing but implied:
- Dockerfile, requirements.txt / Pipfile (README calls for `pip install -r requirements.txt`)

##### README for additional insights
- Features: JWT auth, Pydantic validation, relational DB, Swagger auto-docs, Dockerized, GitHub Actions, pytest
- Tech stack: FastAPI, GitHub Actions
- Endpoints: `/api/estates` (GET, POST, PUT, DELETE)

##### Main components and interactions
a. Components:
- Clients (Web app / Mobile app / CURL)
- API Layer (FastAPI server)
– Routers (endpoints under `/api/estates`)
– Controllers/Services (business logic)
– Models (Pydantic schemas)
– Auth Module (JWT issuance & verification)
- Persistence Layer
– Relational Database (e.g., PostgreSQL)
– ORM or direct SQL driver
- Support Services
– Swagger/OpenAPI UI
– Docker Container & Image Registry
– CI/CD Pipeline (GitHub Actions)
b. Interactions:
1. Client → HTTP request → FastAPI router
2. Router → Auth middleware → verify JWT (or issue on login)
3. Controller/Service → Pydantic validation → prepare DB query
4. Service → Database connector → SQL operations
5. Database → returns data → Service → formats response → Client
6. CI/CD system → on git push → run tests → build Docker image → push to registry → deploy
c. Architectural patterns / principles:
- Layered architecture (Presentation/Controller → Service → Repository → DB)
- Modular design (separate auth, validation, business logic)
- 12-factor app approach (config via env vars, separate build and run)
d. Key technologies:
- FastAPI (ASGI web server)
- Pydantic (data validation)
- Uvicorn / Gunicorn (ASGI server)
- PostgreSQL (relational DB)
- Docker (containerization)
- GitHub Actions (CI/CD)
- Pytest (automated testing)

##### Key reminders
- Be exhaustive: break the service down into routers, middleware, services, repositories.
- External dependencies (DB, container registry, CI server).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (Web/Mobile/CURL)"]:::external

    %% API Server Layer
    subgraph "API Server" 
        direction TB
        AppEntry["App Entry\nsrc/app.js"]:::runtime
        Routers["Routers\n/api/estates"]:::runtime
        Auth["Auth Module\n(JWT Issue & Verify)"]:::cross
        Validation["Validation Layer\n(Pydantic)"]:::cross
        BusinessLogic["Business Logic\n(Services)"]:::runtime
        Repository["Repository Layer\n(DB Connector)"]:::runtime
        SwaggerUI["Swagger UI\n(OpenAPI Docs)"]:::runtime
    end

    %% Database
    DB[(PostgreSQL\nRelational DB)]:::db

    %% CI/CD Pipeline
    subgraph "CI/CD & Deployment"
        direction TB
        GitHub["GitHub Repo"]:::external
        CI["GitHub Actions\n(api-ci.yml)"]:::external
        DockerRegistry["Docker Registry"]:::external
        Deployment["Deployment\n(Container)"]:::external
        TestSuite["Test Suite\ntest/app.test.js"]:::external
        PackageJSON["package.json"]:::external
        PackageLock["package-lock.json"]:::external
        README["README.md"]:::external
        Gitignore[".gitignore"]:::external
    end

    %% Runtime Flows
    Client -->|"HTTP Request"| AppEntry
    AppEntry -->|"route to"| Routers
    Routers -->|"check JWT"| Auth
    Auth -->|"validate payload"| Validation
    Validation -->|"execute business logic"| BusinessLogic
    BusinessLogic -->|"SQL Query"| Repository
    Repository -->|"read/write"| DB
    DB -->|"result set"| BusinessLogic
    BusinessLogic -->|"formatted response"| Routers
    Routers -->|"HTTP Response"| Client
    AppEntry -->|"serve docs"| SwaggerUI

    %% CI/CD Flows
    GitHub -->|"push code"| CI
    CI -->|"run tests"| TestSuite
    CI -->|"build image"| PackageJSON
    CI -->|"lock deps"| PackageLock
    CI -->|"dockerize"| DockerRegistry
    CI -->|"deploy"| Deployment

    %% Click Events
    click AppEntry "https://github.com/renzomedina/realestate-api/blob/main/src/app.js"
    click CI "https://github.com/renzomedina/realestate-api/blob/main/.github/workflows/api-ci.yml"
    click TestSuite "https://github.com/renzomedina/realestate-api/blob/main/test/app.test.js"
    click PackageJSON "https://github.com/renzomedina/realestate-api/blob/main/package.json"
    click PackageLock "https://github.com/renzomedina/realestate-api/blob/main/package-lock.json"
    click README "https://github.com/renzomedina/realestate-api/blob/main/README.md"
    click Gitignore "https://github.com/renzomedina/realestate-api/blob/main/.gitignore"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef db fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef cross fill:#FFA500,stroke:#000,stroke-width:1px
```
