How mhbhuiyan99/connect works
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: app App router · main.py API entry · api API routes · docker-compose.yml Compose
Components 17
Deployment
Container and edge proxy setup for the full stack.
Backend
Python API organized by domain routes, models, schemas, and security.
- API entry · Backend process bootstrap and service startup.
backend/main.py - Config · Centralized backend runtime settings and environment wiring.
backend/config.py - Security · Authentication and authorization logic used by protected routes.
backend/core/security.py - API routes · HTTP route modules for alumni, users, events, notices, auth, admin, approval, skills, and images.
backend/api - Models · Persistent domain models for alumni, events, notices, and users.
backend/models - Schemas · 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 · Route groups and pages for public browsing, auth, admin, and profile flows.
frontend/src/app - API proxy · Catch-all Next.js proxy that forwards frontend requests to backend services.
frontend/src/app/api/[...path]/route.ts - Context · Shared providers and service wiring for auth and app-wide behavior.
frontend/src/context - Auth store · Persistent client-side authentication state and session coordination.
frontend/src/store/authStore.ts - Hooks · Feature hooks that wrap API clients with cached server-state access.
frontend/src/hooks - API clients · Typed resource clients for alumni, events, notices, users, auth, and admin actions.
frontend/src/lib/api - Feature UI · Domain-oriented UI composition for auth, alumni, events, notices, admin, and forms.
frontend/src/components - UI primitives · Reusable low-level interface components shared across the app.
frontend/src/components/ui - Domain types · Frontend domain types aligned with backend entities.
frontend/src/models
Connections 19
- 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.