# prahang/griet-go architecture

> Architecture diagram of the GitHub repository prahang/griet-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prahang/griet-go
- Repository: https://github.com/prahang/griet-go

## Overview

1. **Top-level shape**
   - This repo is split into two deployable applications: `frontend/` and `backend/`.
   - The frontend is a Next.js 14 app; the backend is a Python API that exposes the social app’s domain operations.

2. **Frontend presentation layer**
   - The UI is organized with the Next.js App Router under `frontend/src/app/`.
   - Route groups separate **auth flows** (`login`, `signup`) from the **main app** (`feed/home`, `create`, `explore`, `messages`, `notifications`, `profile/[uid]`).
   - This is a client-heavy app shell with page-level composition rather than a single SPA entry.

3. **Frontend state and auth boundary**
   - Authentication state is centralized in React context (`frontend/src/context/AuthContext.tsx` and `frontend/context/AuthContext.tsx`).
   - Firebase client SDK is used on the frontend for sign-in/sign-up and session state.
   - The frontend likely attaches Firebase identity information to API calls rather than managing its own auth system.

4. **Frontend-to-backend API layer**
   - `frontend/src/lib/api.ts` is the main boundary for talking to the backend.
   - `frontend/src/lib/firebase.ts` holds Firebase client setup.
   - Shared UI components such as `Feed`, `PostCard`, `PostModal`, `EditProfileModal`, `Sidebar`, and `BottomNav` consume data from these layers.

5. **Backend request handling structure**
   - The backend is organized into an entrypoint (`backend/app.py`), configuration (`backend/config.py`), middleware (`backend/middleware.py`), route modules, and service modules.
   - Route files are grouped by domain: `chat`, `notifications`, `posts`, `social`, and `users`.
   - Services under `backend/services/` contain the actual business logic, keeping route handlers thin.

6. **Backend domain boundaries**
   - `posts` handles feed content, creation, likes, and post-related retrieval.
   - `users` handles profiles and user metadata.
   - `social` handles the follow/unfollow graph.
   - `chat` handles direct messaging.
   - `notifications` handles notification generation and retrieval.

7. **Authentication and authorization**
   - The backend uses middleware to validate Firebase ID tokens, acting as the trust boundary for protected endpoints.
   - This means the frontend authenticates with Firebase, then the backend verifies identity before performing user-scoped operations.

8. **Data and infrastructure dependencies**
   - Persistent data lives in **Firebase Firestore** rather than a relational ORM/database.
   - Media uploads go to **Firebase Storage**.
   - The backend uses Firebase Admin credentials from environment configuration, so Firestore/Storage access is server-side only.

9. **Key runtime technologies**
   - Frontend: Next.js, React, TypeScript, Tailwind CSS, and likely Framer Motion for animation.
   - Backend: Python API stack with Firebase Admin integration; the README describes Django 5 / Django REST Framework, while the file layout shows an API app split by routes/services.

10. **Main data flows to show in a diagram**
   - User signs in on the frontend via Firebase Authentication.
   - Frontend sends requests through `api.ts` to backend endpoints.
   - Backend middleware validates the Firebase token.
   - Service layer reads/writes Firestore, and uploads/reads media from Firebase Storage.
   - The frontend renders feed, profile, chat, and notification views from backend data.

11. **Interaction patterns implied by the UI**
   - The app supports a social feed, post creation, profile viewing, follow/unfollow, messaging, and notifications.
   - Pages like `messages/[chatId]` and `profile/[uid]` imply dynamic, per-resource screens backed by backend lookups.

12. **Practical diagram boundaries**
   - Treat `frontend/` as the client presentation and interaction layer.
   - Treat `backend/` as the domain API and authorization layer.
   - Treat Firebase Auth, Firestore, and Storage as external managed services shared by both sides, with the backend owning privileged access.

Main entry points: [`backend/app.py`](https://github.com/prahang/griet-go/blob/main/backend/app.py) (API app), [`frontend/src/lib/api.ts`](https://github.com/prahang/griet-go/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/app/(main)/page.tsx`](https://github.com/prahang/griet-go/blob/main/frontend/src/app/(main)/page.tsx) (Main routes), [`frontend/src/context/AuthContext.tsx`](https://github.com/prahang/griet-go/blob/main/frontend/src/context/AuthContext.tsx) (Auth context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_frontend_auth_routes["Auth routes<br/>Next.js routes<br/>[page.tsx]"]
  node_frontend_main_routes["Main routes<br/>Next.js routes<br/>[page.tsx]"]
  node_frontend_auth_context(("Auth context<br/>React state<br/>[AuthContext.tsx]"))
  node_frontend_api["API client<br/>HTTP client<br/>[api.ts]"]
  node_frontend_firebase["Firebase client<br/>Firebase SDK<br/>[firebase.ts]"]
  node_frontend_ui["UI components<br/>Social UI<br/>[Feed.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>Python entrypoint<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_middleware["Auth middleware<br/>Request middleware<br/>[middleware.py]"]
  node_backend_routes["Route layer<br/>Domain routes<br/>[posts.py]"]
  node_backend_services["Service layer<br/>Domain services<br/>[posts.py]"]
end

subgraph group_managed["Managed Services"]
  node_firebase_auth(("Firebase Auth<br/>Managed identity"))
  node_firestore[("Firestore<br/>Managed datastore")]
  node_storage[("Storage<br/>Managed media store")]
end

node_frontend_app -->|"renders"| node_frontend_auth_routes
node_frontend_app -->|"renders"| node_frontend_main_routes
node_frontend_auth_routes -->|"uses"| node_frontend_auth_context
node_frontend_auth_context -->|"reads session"| node_frontend_firebase
node_frontend_main_routes -->|"composes"| node_frontend_ui
node_frontend_ui -->|"loads data"| node_frontend_api
node_frontend_main_routes -->|"calls"| node_frontend_api
node_frontend_auth_context -->|"attaches identity"| node_frontend_api
node_frontend_firebase -->|"signs in"| node_firebase_auth
node_frontend_api -->|"requests"| node_backend_app
node_backend_app -->|"loads config"| node_backend_config
node_backend_app -->|"wraps"| node_backend_middleware
node_backend_app -->|"dispatches"| node_backend_routes
node_backend_middleware -->|"verifies token"| node_firebase_auth
node_backend_routes -->|"delegates"| node_backend_services
node_backend_services -->|"reads/writes"| node_firestore
node_backend_services -->|"uploads media"| node_storage

click node_frontend_app "https://github.com/prahang/griet-go/blob/main/frontend/src/app/layout.tsx"
click node_frontend_auth_routes "https://github.com/prahang/griet-go/blob/main/frontend/src/app/(auth)/login/page.tsx"
click node_frontend_main_routes "https://github.com/prahang/griet-go/blob/main/frontend/src/app/(main)/page.tsx"
click node_frontend_auth_context "https://github.com/prahang/griet-go/blob/main/frontend/src/context/AuthContext.tsx"
click node_frontend_api "https://github.com/prahang/griet-go/blob/main/frontend/src/lib/api.ts"
click node_frontend_firebase "https://github.com/prahang/griet-go/blob/main/frontend/src/lib/firebase.ts"
click node_frontend_ui "https://github.com/prahang/griet-go/blob/main/frontend/src/components/Feed.tsx"
click node_backend_app "https://github.com/prahang/griet-go/blob/main/backend/app.py"
click node_backend_config "https://github.com/prahang/griet-go/blob/main/backend/config.py"
click node_backend_middleware "https://github.com/prahang/griet-go/blob/main/backend/middleware.py"
click node_backend_routes "https://github.com/prahang/griet-go/blob/main/backend/routes/posts.py"
click node_backend_services "https://github.com/prahang/griet-go/blob/main/backend/services/posts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_auth_routes,node_frontend_main_routes,node_frontend_auth_context,node_frontend_api,node_frontend_firebase,node_frontend_ui toneBlue
class node_backend_app,node_backend_config,node_backend_middleware,node_backend_routes,node_backend_services toneAmber
class node_firebase_auth,node_firestore,node_storage toneMint
```

## Components

### Frontend

Next.js client app, route composition, auth state, and UI layer.

- [App shell](https://github.com/prahang/griet-go/blob/main/frontend/src/app/layout.tsx): Next.js layout · Root frontend app shell and route composition entry. · `frontend/src/app/layout.tsx`
- [Auth routes](https://github.com/prahang/griet-go/blob/main/frontend/src/app/(auth)/login/page.tsx): Next.js routes · Login and signup flows under the App Router auth group. · `frontend/src/app/(auth)/login/page.tsx`
- [Main routes](https://github.com/prahang/griet-go/blob/main/frontend/src/app/(main)/page.tsx): Next.js routes · Feed, create, explore, messages, notifications, and profile screens. · `frontend/src/app/(main)/page.tsx`
- [Auth context](https://github.com/prahang/griet-go/blob/main/frontend/src/context/AuthContext.tsx): React state · Centralized client-side auth/session state. · `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/prahang/griet-go/blob/main/frontend/src/lib/api.ts): HTTP client · Frontend boundary for backend requests. · `frontend/src/lib/api.ts`
- [Firebase client](https://github.com/prahang/griet-go/blob/main/frontend/src/lib/firebase.ts): Firebase SDK · Client-side Firebase setup for sign-in and session handling. · `frontend/src/lib/firebase.ts`
- [UI components](https://github.com/prahang/griet-go/blob/main/frontend/src/components/Feed.tsx): Social UI · Shared feed, post, navigation, and modal components. · `frontend/src/components/Feed.tsx`

### Backend

Python API entrypoint, middleware, route handlers, and domain services.

- [API app](https://github.com/prahang/griet-go/blob/main/backend/app.py): Python entrypoint · Backend application entrypoint. · `backend/app.py`
- [Config](https://github.com/prahang/griet-go/blob/main/backend/config.py): Environment config · Backend configuration and Firebase credentials setup. · `backend/config.py`
- [Auth middleware](https://github.com/prahang/griet-go/blob/main/backend/middleware.py): Request middleware · Validates Firebase ID tokens and enforces protected access. · `backend/middleware.py`
- [Route layer](https://github.com/prahang/griet-go/blob/main/backend/routes/posts.py): Domain routes · Thin request handlers for posts, users, social graph, chat, and notifications. · `backend/routes/posts.py`
- [Service layer](https://github.com/prahang/griet-go/blob/main/backend/services/posts.py): Domain services · Business logic for posts, users, social graph, chat, and notifications. · `backend/services/posts.py`

### Managed Services

Firebase services used for identity, data, and media storage.

- **Firebase Auth**: Managed identity · External identity provider used by the client and verified by the backend.
- **Firestore**: Managed datastore · Primary persistent store for social app data.
- **Storage**: Managed media store · Media upload and retrieval backend for user content.

## Connections

- App shell → Auth routes: renders · Root app shell composes auth flows.
- App shell → Main routes: renders · Root app shell composes main app routes.
- Auth routes → Auth context: uses · Auth pages depend on shared auth state.
- Auth context → Firebase client: reads session · Auth context is backed by the Firebase client SDK.
- Main routes → UI components: composes · Main screens render shared social UI components.
- UI components → API client: loads data · UI components fetch and mutate backend-backed content.
- Main routes → API client: calls · Main app routes access backend APIs through the client boundary.
- Auth context → API client: attaches identity · Frontend requests carry authenticated user identity to the API layer.
- Firebase client → Firebase Auth: signs in · Client SDK authenticates users with Firebase.
- API client → API app: requests · Frontend API client talks to the backend entrypoint.
- API app → Config: loads config · Backend app initializes with environment configuration.
- API app → Auth middleware: wraps · Request pipeline passes through auth middleware.
- API app → Route layer: dispatches · Backend app dispatches requests to domain routes.
- Auth middleware → Firebase Auth: verifies token · Middleware validates Firebase ID tokens.
- Route layer → Service layer: delegates · Route handlers forward business work to services.
- Service layer → Firestore: reads/writes · Services persist and query social data in Firestore.
- Service layer → Storage: uploads media · Services use storage for images and other uploaded content.