# och1ai/taller1 architecture

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

- Interactive diagram: https://gitdiagram.com/och1ai/taller1
- Repository: https://github.com/och1ai/taller1

## Overview

##### Project Type and Purpose
- This is a single-purpose microservice in a larger ecosystem: a RESTful **User Service API** built with FastAPI.
- It provides user management (CRUD), JWT-based authentication/authorization, and audit logging, all backed by a PostgreSQL database.
- There is also a small **mock_main_api** container used for local/integration testing of how the User Service would interact with a “main” application.

##### High-Level Components
a. Clients
- Web/UIs or other services that consume the REST API
- Automated test runner (test_api.py, run_tests.sh)
- Swagger/OpenAPI UI and ReDoc
b. API Layer (user_service/app/main.py)
- FastAPI application with routers under `/api/v1`
- Dependency‐injection system for DB sessions and security
c. Business Logic Layer
- Endpoint controllers (`app/api/v1/endpoints/*.py`)
- Authentication (`app/core/auth.py`), security (`app/core/security.py`), configuration (`app/core/config.py`)
d. Data Access Layer
- CRUD classes implementing the Repository pattern (`app/crud/*.py`)
- Pydantic schemas (`app/schemas/*.py`)
- SQLAlchemy models (`app/models/*.py`)
- Alembic‐style migrations and seeders
e. Database Layer
- PostgreSQL instance defined in docker-compose.yml
- Tables: users, audit_logs
f. Auxiliary Services
- mock_main_api container to simulate interactions
- Local script runners for testing, migration, and seeding

##### Relationships and Data Flows
- Clients → HTTP request → FastAPI API Layer
- API Layer ↔ DI of DB Session → Business Logic Layer → CRUD → PostgreSQL
- On sensitive admin actions, Observer pattern logs to audit_logs table
- External service (mock_main_api) calls user routes during integration tests
- Tests invoke endpoints (via base URL) and validate responses

##### Architectural Patterns & Design Principles
- **Layered Architecture** separating concerns end-to-end
- **Repository Pattern** for abstracting database operations
- **Dependency Injection** via FastAPI’s `Depends`
- **Factory** for token creation (JWT) in `app/core/auth.py`
- **Observer** for audit logging inside endpoint handlers
- **Singleton** for global settings in `app/core/config.py`
- **Soft Delete** strategy in CRUD remove operations

##### Essential Elements to Capture
- The **FastAPI** server container (user_service) exposing `/api/v1` endpoints
- The **PostgreSQL** container with tables `users` and `audit_logs`
- The **mock_main_api** container used for integration tests
- The **test runner** and **Swagger/OpenAPI** UIs as consuming clients
- The **dependency injection** pipeline (DB session, security)
- The **audit observer** hooking into delete/update operations
- Docker Compose topology: network links among `user_service`, `postgres`, `mock_main_api`

##### Leveraging Existing PlantUML Files
- The project includes `docs/architecture.puml`, `docs/database.puml`, `docs/auth_flow.puml`. Use or adapt these as a starting point.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        WebUI["Web/UIs or Other Services"]:::client
        TestShell["run_tests.sh"]:::client
        TestAPI["test_api.py"]:::client
        SwaggerUI["Swagger/OpenAPI & ReDoc UI"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["FastAPI App"]:::api
        Routers["Routers (/api/v1)"]:::api
        Deps["Dependency Injection"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Auth["core/auth.py"]:::logic
        Security["core/security.py"]:::logic
        Config["core/config.py"]:::logic
        DBDep["core/database.py"]:::logic
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        CRUD["CRUD Repositories"]:::data
        Schemas["Pydantic Schemas"]:::data
        Models["SQLAlchemy Models"]:::data
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        Postgres["PostgreSQL"]:::db
        Migrations["Migrations & Seeders"]:::db
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        Mock["mock_main_api (container)"]:::aux
        Entrypoint["entrypoint.sh"]:::aux
        MigrateScript["migrations.sh"]:::aux
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocArch["architecture.puml"]:::docs
        DocAuth["auth_flow.puml"]:::docs
        DocDB["database.puml"]:::docs
    end

    %% Docker Compose Topology
    subgraph "Docker Compose Network"
        direction TB
        Service["user_service (container)"]:::docker
        Postgres
        Mock
    end

    %% Relationships
    WebUI -->|HTTP| API
    TestShell -->|HTTP| API
    TestAPI -->|HTTP| API
    SwaggerUI -->|UI| API
    Mock -->|HTTP| API

    API -->|uses| Routers
    Routers -->|depends on| Deps
    Routers -->|invokes| Auth
    Routers -->|invokes| Security
    Routers -->|uses| DBDep

    Auth -->|calls| CRUD
    Security -->|calls| CRUD
    DBDep -->|provides| CRUD

    CRUD -->|maps to| Models
    CRUD -->|maps to| Schemas
    CRUD -->|executes SQL| Postgres

    Entrypoint -->|runs| Migrations
    MigrateScript -->|runs| Migrations
    Migrations -->|applies| Postgres

    %% Click Events
    click TestShell "https://github.com/och1ai/taller1/blob/main/run_tests.sh"
    click TestAPI "https://github.com/och1ai/taller1/blob/main/test_api.py"
    click SwaggerUI "https://github.com/och1ai/taller1/blob/main/user_service/app/main.py"
    click API "https://github.com/och1ai/taller1/blob/main/user_service/app/main.py"
    click Routers "https://github.com/och1ai/taller1/blob/main/user_service/app/api/v1/api.py"
    click Deps "https://github.com/och1ai/taller1/blob/main/user_service/app/api/deps.py"
    click Auth "https://github.com/och1ai/taller1/blob/main/user_service/app/core/auth.py"
    click Security "https://github.com/och1ai/taller1/blob/main/user_service/app/core/security.py"
    click Config "https://github.com/och1ai/taller1/blob/main/user_service/app/core/config.py"
    click DBDep "https://github.com/och1ai/taller1/blob/main/user_service/app/core/database.py"
    click CRUD "https://github.com/och1ai/taller1/blob/main/user_service/app/crud/base.py"
    click CRUD "https://github.com/och1ai/taller1/blob/main/user_service/app/crud/user.py"
    click CRUD "https://github.com/och1ai/taller1/blob/main/user_service/app/crud/audit.py"
    click Schemas "https://github.com/och1ai/taller1/blob/main/user_service/app/schemas/user.py"
    click Schemas "https://github.com/och1ai/taller1/blob/main/user_service/app/schemas/auth.py"
    click Schemas "https://github.com/och1ai/taller1/blob/main/user_service/app/schemas/audit.py"
    click Models "https://github.com/och1ai/taller1/blob/main/user_service/app/models/user.py"
    click Models "https://github.com/och1ai/taller1/blob/main/user_service/app/models/audit.py"
    click Postgres "https://github.com/och1ai/taller1/blob/main/docker-compose.yml"
    click Migrations "https://github.com/och1ai/taller1/blob/main/user_service/app/migrations/002_add_is_admin.sql"
    click Migrations "https://github.com/och1ai/taller1/blob/main/user_service/app/migrations/003_create_audit_logs.sql"
    click Migrations "https://github.com/och1ai/taller1/blob/main/user_service/app/migrations/update_email_constraint.sql"
    click Migrations "https://github.com/och1ai/taller1/blob/main/user_service/app/seeders/seed.py"
    click Mock "https://github.com/och1ai/taller1/tree/main/mock_main_api/Dockerfile"
    click Mock "https://github.com/och1ai/taller1/blob/main/mock_main_api/main.py"
    click Mock "https://github.com/och1ai/taller1/blob/main/mock_main_api/requirements.txt"
    click Entrypoint "https://github.com/och1ai/taller1/blob/main/user_service/entrypoint.sh"
    click MigrateScript "https://github.com/och1ai/taller1/blob/main/user_service/migrations.sh"
    click DocArch "https://github.com/och1ai/taller1/blob/main/docs/architecture.puml"
    click DocAuth "https://github.com/och1ai/taller1/blob/main/docs/auth_flow.puml"
    click DocDB "https://github.com/och1ai/taller1/blob/main/docs/database.puml"

    %% Styles
    classDef client fill:#D0E7FF,stroke:#369,stroke-width:1px
    classDef api fill:#B2F2E1,stroke:#0A9,stroke-width:1px
    classDef logic fill:#D7FFD9,stroke:#0A7,stroke-width:1px
    classDef data fill:#FFF9B0,stroke:#EA0,stroke-width:1px
    classDef db fill:#FFCBA3,stroke:#E65,stroke-width:1px
    classDef aux fill:#E0D7FF,stroke:#70A,stroke-width:1px
    classDef docker fill:#FFDDE0,stroke:#F33,stroke-width:1px
    classDef docs fill:#EDEDED,stroke:#999,stroke-width:1px
```
