# mhbhuiyan99/connect architecture

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

- Interactive diagram: https://gitdiagram.com/mhbhuiyan99/connect
- Repository: https://github.com/mhbhuiyan99/connect

## Overview

1. This repo is a two-tier alumni/community management system: a Python backend API and a Next.js frontend. The deployment is containerized with separate Dockerfiles, and `docker-compose.yml` plus `conf/nginx.conf` suggest an Nginx front door proxying to the app services.

2. The backend is organized as a domain-based HTTP API. `backend/main.py` is the entry point, `backend/api/*` contains route modules, `backend/core/security.py` holds authentication/authorization logic, and `backend/config.py` centralizes runtime configuration. The presence of `pyproject.toml` and `uv.lock` indicates a modern Python packaging/runtime setup.

3. Backend boundaries are cleanly split between persistence and transport: `backend/models/*` defines domain data models, while `backend/schema/*` defines request/response shapes. This implies the API layer translates between wire formats and stored entities rather than exposing models directly.

4. The backend’s main business domains are alumni, users, events, notices, auth, admin, approval, skills, and image handling. These are separated into individual route modules (`alumni.py`, `event.py`, `notice.py`, `users.py`, `auth.py`, etc.), which is a strong signal that each subsystem owns its own endpoints and workflow.

5. Authentication and access control are a first-class backend concern. `core/security.py` plus the auth route and approval/admin modules indicate role-based access, likely with login/session or token validation and a separate approval step for user/alumni records before they become fully active.

6. The frontend is a Next.js App Router application with route groups for auth, admin, profile, and public browsing. Pages under `src/app/*` map to the major user journeys: landing/home, about, alumni directory and detail views, events, notices, profile management, sign-in/sign-up, and an admin console.

7. Frontend data access is layered. `src/lib/api/*` contains resource-specific API clients, `src/hooks/*` wraps those clients into feature hooks, and `src/app/api/[...path]/route.ts` acts as a catch-all proxy layer. That proxy boundary is important: the UI can route backend calls through the Next.js app instead of talking to the backend directly.

8. Client state and cross-cutting behavior are centralized in a few shared utilities: `AuthProvider`, `ServiceContext`, `authStore`, and the `react-query-provider`. This points to a hybrid model where authentication and global service wiring live in context/store, while server state is cached and synchronized through React Query.

9. UI composition is feature-oriented. Reusable primitives live in `src/components/ui`, while higher-level components are grouped by domain (`admin`, `alumni`, `event`, `notice`, `auth`, `form`, `about`). Most pages appear to be thin composition layers over these components, which keeps domain logic out of route files.

10. The key user flows are: public browsing of alumni/events/notices; account creation and sign-in; alumni profile submission/update; admin review and approval; and admin CRUD for alumni, events, notices, and users. The file structure suggests the system’s core purpose is to manage a community directory and its associated content with controlled moderation.

11. Several route/layout splits reinforce role boundaries: `(auth)` for login/signup, `/admin/*` for privileged operations, and `/profile/*` for signed-in user self-service. That separation is likely mirrored by backend authorization checks so the same domain data is exposed differently based on role.

12. Shared domain types exist on the frontend in `src/models/*` for Alumni, Event, Notice, User, and Company. These mirror the backend entities and help keep the UI, API clients, and server responses aligned around the same domain vocabulary.

Main entry points: [`frontend/src/app`](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/app) (App router), [`backend/main.py`](https://github.com/mhbhuiyan99/connect/blob/main/backend/main.py) (API entry), [`backend/api`](https://github.com/mhbhuiyan99/connect/tree/main/backend/api) (API routes), [`docker-compose.yml`](https://github.com/mhbhuiyan99/connect/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_nginx["Nginx<br/>edge proxy<br/>[nginx.conf]"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["API entry<br/>python app<br/>[main.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_security["Security<br/>authz/authn<br/>[security.py]"]
  node_backend_routes["API routes<br/>domain endpoints"]
  node_backend_models["Models<br/>domain entities"]
  node_backend_schemas["Schemas<br/>wire contracts"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["App router<br/>nextjs pages"]
  node_frontend_api_proxy["API proxy<br/>route handler<br/>[route.ts]"]
  node_frontend_context["Context<br/>client state"]
  node_frontend_store["Auth store<br/>client auth state<br/>[authStore.ts]"]
  node_frontend_hooks["Hooks"]
  node_frontend_api["API clients<br/>service clients"]
  node_frontend_components["Feature UI<br/>components"]
  node_frontend_ui["UI primitives<br/>design system"]
  node_frontend_models["Domain types<br/>shared models"]
end

node_compose -->|"routes through"| node_nginx
node_compose -->|"starts"| node_backend_entry
node_compose -->|"starts"| node_frontend_app
node_nginx -->|"proxies to"| node_frontend_app
node_nginx -->|"proxies API"| node_backend_entry
node_backend_entry -->|"loads"| node_backend_config
node_backend_entry -->|"registers"| node_backend_routes
node_backend_routes -->|"guards"| node_backend_security
node_backend_routes -->|"persists"| node_backend_models
node_backend_routes -->|"validates"| node_backend_schemas
node_frontend_app -->|"delegates API"| node_frontend_api_proxy
node_frontend_app -->|"uses"| node_frontend_context
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_context -->|"coordinates"| node_frontend_store
node_frontend_components -->|"builds on"| node_frontend_ui
node_frontend_components -->|"reads data via"| node_frontend_hooks
node_frontend_hooks -->|"calls"| node_frontend_api
node_frontend_api -->|"returns"| node_frontend_models
node_frontend_api_proxy -->|"forwards to"| node_backend_entry

click node_nginx "https://github.com/mhbhuiyan99/connect/blob/main/conf/nginx.conf"
click node_compose "https://github.com/mhbhuiyan99/connect/blob/main/docker-compose.yml"
click node_backend_entry "https://github.com/mhbhuiyan99/connect/blob/main/backend/main.py"
click node_backend_config "https://github.com/mhbhuiyan99/connect/blob/main/backend/config.py"
click node_backend_security "https://github.com/mhbhuiyan99/connect/blob/main/backend/core/security.py"
click node_backend_routes "https://github.com/mhbhuiyan99/connect/tree/main/backend/api"
click node_backend_models "https://github.com/mhbhuiyan99/connect/tree/main/backend/models"
click node_backend_schemas "https://github.com/mhbhuiyan99/connect/tree/main/backend/schema"
click node_frontend_app "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/app"
click node_frontend_api_proxy "https://github.com/mhbhuiyan99/connect/blob/main/frontend/src/app/api/[...path]/route.ts"
click node_frontend_context "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/context"
click node_frontend_store "https://github.com/mhbhuiyan99/connect/blob/main/frontend/src/store/authStore.ts"
click node_frontend_hooks "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/hooks"
click node_frontend_api "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/lib/api"
click node_frontend_components "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/components"
click node_frontend_ui "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/components/ui"
click node_frontend_models "https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/models"

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_nginx,node_compose toneBlue
class node_backend_entry,node_backend_config,node_backend_security,node_backend_routes,node_backend_models,node_backend_schemas toneAmber
class node_frontend_app,node_frontend_api_proxy,node_frontend_context,node_frontend_store,node_frontend_hooks,node_frontend_api,node_frontend_components,node_frontend_ui,node_frontend_models toneMint
```

## Components

### Deployment

Container and edge proxy setup for the full stack.

- [Nginx](https://github.com/mhbhuiyan99/connect/blob/main/conf/nginx.conf): edge proxy · Front-door reverse proxy for the deployed app stack. · `conf/nginx.conf`
- [Compose](https://github.com/mhbhuiyan99/connect/blob/main/docker-compose.yml): orchestration · Container composition for backend, frontend, and proxy services. · `docker-compose.yml`

### Backend

Python API organized by domain routes, models, schemas, and security.

- [API entry](https://github.com/mhbhuiyan99/connect/blob/main/backend/main.py): python app · Backend process bootstrap and service startup. · `backend/main.py`
- [Config](https://github.com/mhbhuiyan99/connect/blob/main/backend/config.py): runtime config · Centralized backend runtime settings and environment wiring. · `backend/config.py`
- [Security](https://github.com/mhbhuiyan99/connect/blob/main/backend/core/security.py): authz/authn · Authentication and authorization logic used by protected routes. · `backend/core/security.py`
- [API routes](https://github.com/mhbhuiyan99/connect/tree/main/backend/api): domain endpoints · HTTP route modules for alumni, users, events, notices, auth, admin, approval, skills, and images. · `backend/api`
- [Models](https://github.com/mhbhuiyan99/connect/tree/main/backend/models): domain entities · Persistent domain models for alumni, events, notices, and users. · `backend/models`
- [Schemas](https://github.com/mhbhuiyan99/connect/tree/main/backend/schema): wire contracts · Request and response shapes for API payloads. · `backend/schema`

### Frontend

Next.js app with routed pages, feature components, data access, and shared state.

- [App router](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/app): nextjs pages · Route groups and pages for public browsing, auth, admin, and profile flows. · `frontend/src/app`
- [API proxy](https://github.com/mhbhuiyan99/connect/blob/main/frontend/src/app/api/[...path]/route.ts): route handler · Catch-all Next.js proxy that forwards frontend requests to backend services. · `frontend/src/app/api/[...path]/route.ts`
- [Context](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/context): client state · Shared providers and service wiring for auth and app-wide behavior. · `frontend/src/context`
- [Auth store](https://github.com/mhbhuiyan99/connect/blob/main/frontend/src/store/authStore.ts): client auth state · Persistent client-side authentication state and session coordination. · `frontend/src/store/authStore.ts`
- [Hooks](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/hooks): data hooks · Feature hooks that wrap API clients with cached server-state access. · `frontend/src/hooks`
- [API clients](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/lib/api): service clients · Typed resource clients for alumni, events, notices, users, auth, and admin actions. · `frontend/src/lib/api`
- [Feature UI](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/components): components · Domain-oriented UI composition for auth, alumni, events, notices, admin, and forms. · `frontend/src/components`
- [UI primitives](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/components/ui): design system · Reusable low-level interface components shared across the app. · `frontend/src/components/ui`
- [Domain types](https://github.com/mhbhuiyan99/connect/tree/main/frontend/src/models): shared models · Frontend domain types aligned with backend entities. · `frontend/src/models`

## Connections

- Compose → Nginx: routes through · Compose includes the proxy layer for inbound traffic.
- Compose → API entry: starts · Compose runs the backend service container.
- Compose → App router: starts · Compose runs the frontend service container.
- Nginx → App router: proxies to · Edge proxy forwards browser traffic to the web app.
- Nginx → API entry: proxies API · API requests are routed toward the backend service.
- API entry → Config: loads · Startup wires runtime configuration into the API process.
- API entry → API routes: registers · Main entry exposes domain route modules.
- API routes → Security: guards · Protected endpoints depend on auth checks and role control.
- API routes → Models: persists · Route handlers operate on domain entities.
- API routes → Schemas: validates · Handlers translate request and response payloads through schemas.
- App router → API proxy: delegates API · App routes can send backend calls through the proxy boundary.
- App router → Context: uses · Layouts and pages consume shared providers.
- App router → Feature UI: composes · Pages are built from feature-oriented components.
- Context → Auth store: coordinates · Providers and shared state cooperate around auth/session state.
- Feature UI → UI primitives: builds on · Feature components are assembled from reusable primitives.
- Feature UI → Hooks: reads data via · Domain UI uses hooks for server-state access.
- Hooks → API clients: calls · Hooks wrap the resource-specific API clients.
- API clients → Domain types: returns · Client contracts are aligned to shared domain types.
- API proxy → API entry: forwards to · Proxy handler relays requests to the backend API.
