# chillin-s-playground/eggchatter-web-app-be architecture

> Architecture diagram of the GitHub repository chillin-s-playground/eggchatter-web-app-be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chillin-s-playground/eggchatter-web-app-be
- Repository: https://github.com/chillin-s-playground/eggchatter-web-app-be

## Overview

##### Project type and purpose
- This is a backend‐only RESTful API service called “EggChatter Backend,” built with FastAPI.
- Purpose: provide user authentication (JWT), chat messaging, and “easter egg” GIF features, persisting data in MongoDB.

##### File structure
- Top level:
- app/main.py – entry point (FastAPI app)
- app/core – configuration, DB connection, security, shared exceptions
- app/routers – HTTP endpoints grouped by domain (auth, users, easter_egg, chats)
- app/services – business logic layer (auth, users, easter_egg, chats)
- app/models – ORM/data models for MongoDB collections
- app/schemas – Pydantic request/response schemas
- tests – unit tests
- Config files: pyproject.toml (Poetry), .env for runtime variables, pytest.ini for testing

##### README insights
- Tech stack: FastAPI, MongoDB, Pydantic, JWT (HS256), Poetry
- Features: authentication, real‐time chat (via REST/WebSockets?), easter‐eggs API
- Runtime: uvicorn on port 8080

##### Main components
a. External Clients (Web/Mobile)
b. API Gateway / FastAPI App
- Entry point (app/main.py)
- Routers (auth, users, chats, easter_egg)
c. Core Layer
- Config (env variables)
- Security (JWT encoding/verification)
- Database connector (MongoDB client)
d. Service Layer
- AuthService, UserService, ChatService, EasterEggService
- Implements business logic, calls models & core utilities
e. Data Layer
- MongoDB collections via Models (User, Chat, Friend, EasterEgg)
f. External Dependencies
- MongoDB instance
- Possibly third‐party GIF API or CDN for easter eggs

##### Relationships and data flow
- Client → HTTP Request → FastAPI (main)
- FastAPI Router → corresponding Service
- Service → Core Database module → MongoDB
- Service → Core Security module → sign/verify JWT
- Service → external GIF API (for easter eggs)
- Response back through Router → Client

##### Architectural patterns & principles
- Layered architecture:
1. Presentation/API layer (routers)
2. Business logic layer (services)
3. Data access layer (models + core database)
- Separation of concerns: config/security isolated in core
- Use of Pydantic schemas to enforce data contracts
- Dependency injection (FastAPI’s Depends) to wire config, DB, and services

##### Elements
- API entrypoint (app/main.py)
- Router modules grouped by domain
- Service modules
- Core modules (config, database, security)
- MongoDB instance
- External GIF/Media service

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Clients["External Clients<br/>(Web/Mobile)"]:::external

    %% API Layer
    Main["FastAPI App<br/>(app/main.py)"]:::api
    subgraph "API Layer"
        AuthRouter["AuthRouter"]:::api
        UserRouter["UserRouter"]:::api
        ChatRouter["ChatRouter"]:::api
        EasterEggRouter["EasterEggRouter"]:::api
    end

    %% Schemas Layer
    subgraph "Schemas (DTO)" 
        AuthSchemas["Auth Schemas"]:::schema
        UserSchemas["User Schemas"]:::schema
        ChatSchemas["Chat Schemas"]:::schema
        EasterEggSchemas["EasterEgg Schemas"]:::schema
    end

    %% Service Layer
    subgraph "Service Layer"
        AuthService["AuthService"]:::service
        UserService["UserService"]:::service
        ChatService["ChatService"]:::service
        EasterEggService["EasterEggService"]:::service
    end

    %% Core Layer
    subgraph "Core Layer"
        Config["Config<br/>(.env)"]:::core
        Security["Security<br/>(JWT)"]:::core
        DatabaseCore["Database Connector"]:::core
        Exceptions["Exceptions"]:::core
        BaseCore["Base Utilities"]:::core
    end

    %% Data Models Layer
    subgraph "Data Models"
        BaseModelUtil["Base Model Utilities"]:::data
        UserModel["UserModel"]:::data
        ChatModel["ChatModel"]:::data
        FriendModel["FriendModel"]:::data
        EasterEggModel["EasterEggModel"]:::data
    end

    %% External Dependencies
    MongoDB[(MongoDB)]:::external
    ExternalGIF["External GIF API"]:::external

    %% Connections
    Clients --> Main
    Main --> AuthRouter
    Main --> UserRouter
    Main --> ChatRouter
    Main --> EasterEggRouter

    AuthRouter --> AuthSchemas
    UserRouter --> UserSchemas
    ChatRouter --> ChatSchemas
    EasterEggRouter --> EasterEggSchemas

    AuthSchemas --> AuthService
    UserSchemas --> UserService
    ChatSchemas --> ChatService
    EasterEggSchemas --> EasterEggService

    AuthService --> Config
    AuthService --> Security
    AuthService --> DatabaseCore
    AuthService --> Exceptions
    AuthService --> BaseCore
    AuthService --> UserModel

    UserService --> Config
    UserService --> DatabaseCore
    UserService --> Exceptions
    UserService --> BaseCore
    UserService --> UserModel
    UserService --> FriendModel

    ChatService --> DatabaseCore
    ChatService --> Exceptions
    ChatService --> BaseCore
    ChatService --> ChatModel
    ChatService --> FriendModel

    EasterEggService --> Config
    EasterEggService --> DatabaseCore
    EasterEggService --> Exceptions
    EasterEggService --> BaseCore
    EasterEggService --> EasterEggModel
    EasterEggService --> ExternalGIF

    UserModel --> MongoDB
    ChatModel --> MongoDB
    FriendModel --> MongoDB
    EasterEggModel --> MongoDB
    BaseModelUtil -.-> MongoDB

    %% Click Events
    click Main "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/main.py"
    click AuthRouter "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/routers/auth.py"
    click UserRouter "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/routers/users.py"
    click Config "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/core/config.py"
    click DatabaseCore "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/core/database.py"
    click Security "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/core/security.py"
    click Exceptions "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/core/exceptions.py"
    click BaseCore "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/core/base.py"
    click AuthService "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/services/auth.py"
    click UserService "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/services/users.py"
    click UserModel "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/models/users.py"
    click ChatModel "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/models/chats.py"
    click FriendModel "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/models/friends.py"
    click EasterEggModel "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/models/easter_eggs.py"
    click BaseModelUtil "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/models/base.py"
    click AuthSchemas "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/schemas/auth.py"
    click UserSchemas "https://github.com/chillin-s-playground/eggchatter-web-app-be/blob/main/app/schemas/users.py"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#E6FFED,stroke:#28a745,color:#28a745;
    classDef data fill:#FFF5E6,stroke:#d29d00,color:#d29d00;
    classDef core fill:#FFF0F6,stroke:#d6336c,color:#d6336c;
    classDef schema fill:#F0F7FF,stroke:#0366d6,color:#0366d6,stroke-dasharray: 5 5;
    classDef external fill:#F8F9FA,stroke:#6c757d,color:#6c757d;
```
