# randroids-dojo/typescript-and-python-bootstrap architecture

> Architecture diagram of the GitHub repository randroids-dojo/typescript-and-python-bootstrap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/randroids-dojo/typescript-and-python-bootstrap
- Repository: https://github.com/randroids-dojo/typescript-and-python-bootstrap

## Overview

##### Project Type and Purpose
- This is a *full-stack web application template* with separate authentication, API, and UI layers.
- Purpose: Provide user registration/login (Better Auth), profile management, and a shared counter feature.

##### File Structure
- Top-level directories:
- frontend/ (React TS + Vite + Tailwind)
- auth-service/ (Node.js Better Auth service)
- backend/ (Python FastAPI REST API)
- nginx/ (reverse-proxy config)
- Orchestration: docker-compose.yml & docker-compose.prod.yml
- Supporting infra: PostgreSQL & Redis (implied by README), .env.example for configs

##### README for Key Insights
- Tech Stack: React → Nginx → Node.js Auth → FastAPI → PostgreSQL & Redis
- All services containerized; single entry point (Nginx) unifies ports
- Docker Compose for dev/prod, Azure readiness

##### Main Components and Their Interactions
a. User (Browser)
- Loads the React SPA (served as static assets via Nginx)
- Calls REST endpoints for login, signup, profile, counter
b. Nginx Reverse Proxy
- Listens on port 80/443
- Routes “/auth”→Auth Service, “/api”→FastAPI backend, “/“→Static frontend
c. Frontend Service (React + Vite)
- Exposes static files (index.html, compiled JS/CSS)
- Contains auth-client.ts to talk to Auth Service
- Contains api.ts to call FastAPI endpoints
d. Auth Service (Node.js Better Auth)
- Handles /auth/signin, signup, session
- Uses secure cookies, stores sessions in Redis (cache)
- Persists user records in PostgreSQL
e. Backend API (FastAPI)
- Endpoints: /api/health, /api/user, /api/counter
- Enforces session-based auth (reads cookie, validates with Auth Service or Redis)
- Reads/writes PostgreSQL (user_profile), Redis (counter cache?)
f. Data Stores
- PostgreSQL: user_profiles, counters
- Redis: session store, potential cache for counter
g. Docker Compose
- Defines and networks all containers: frontend, auth-service, backend, postgres, redis, nginx
- Shared Docker network for inter-service communication

##### Architectural Patterns and Design Principles
- API Gateway pattern (Nginx as single ingress)
- Separation of concerns: UI, Auth microservice, API microservice, Data stores
- Session-based authentication with secure cookies
- Container-based isolation and orchestration
- Modular code structure (frontend/src/components, backend/app/routers/models)

##### Don’t Overthink – Maximize Modular Components
- Every service: Docker Compose, .env, code‐review artifacts (can be omitted if not part of runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Browser)"]:::client

    %% Reverse Proxy
    Nginx["Nginx Reverse Proxy\n(80/443)"]:::proxy

    %% Containers Orchestration
    subgraph "Orchestration (Docker Compose)" 
        direction TB
        Compose["Docker Compose"]:::infra

        subgraph "Services & Datastores"
            direction TB
            Frontend["Frontend Service\nReact+Vite (3000)"]:::service
            Auth["Auth Service\nBetter Auth (3001)"]:::service
            Backend["FastAPI Backend\nAPI (8000)"]:::service
            Postgres["PostgreSQL"]:::database
            Redis["Redis"]:::database
        end
    end

    %% Connections
    User -->|HTTP| Nginx
    Nginx -->|"Static GET"| Frontend
    Nginx -->|"/auth"| Auth
    Nginx -->|"/api"| Backend

    Frontend -->|"/auth, /api"| Auth
    Frontend -->|"/api"| Backend

    Auth -->|SQL| Postgres
    Auth -->|Session R/W| Redis

    Backend -->|SQL| Postgres
    Backend -->|Cache R/W| Redis

    Compose --> Nginx
    Compose --> Frontend
    Compose --> Auth
    Compose --> Backend
    Compose --> Postgres
    Compose --> Redis

    %% Click Events
    click Frontend "https://github.com/randroids-dojo/typescript-and-python-bootstrap/tree/main/frontend/"
    click Auth "https://github.com/randroids-dojo/typescript-and-python-bootstrap/tree/main/auth-service/"
    click Backend "https://github.com/randroids-dojo/typescript-and-python-bootstrap/tree/main/backend/app/"
    click Nginx "https://github.com/randroids-dojo/typescript-and-python-bootstrap/tree/main/nginx/"
    click Compose "https://github.com/randroids-dojo/typescript-and-python-bootstrap/blob/main/docker-compose.yml"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef proxy fill:#004080,stroke:#fff,stroke-width:1px,color:#fff
    classDef service fill:#FFA500,stroke:#000,stroke-width:1px
    classDef database fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
