# prahang/research-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/prahang/research-management-system
- Repository: https://github.com/prahang/research-management-system

## Overview

1. **System shape**
   - RAMS is a two-tier application: a **Next.js frontend** and a **Flask API backend**, backed by a relational database.
   - The frontend is a presentation and interaction layer; the backend owns authentication, authorization, business rules, persistence, and analytics aggregation.

2. **Frontend boundary**
   - The `frontend/src/app` tree shows an **App Router** structure with distinct pages for dashboard, login, signup, projects, publications, and user profiles.
   - Shared UI is split into reusable components such as `Charts`, `OrgChart`, navigation, theme controls, and a small shadcn/ui component set.
   - `frontend/src/lib/api.ts` is the main client-side integration point to the backend, so the browser talks to the API through a centralized fetch wrapper rather than ad hoc network calls.

3. **Backend boundary**
   - The Flask app is organized around route blueprints in `backend/app/routes`: `auth`, `projects`, `publications`, `dashboard`, `users`, and `search`.
   - `backend/app/__init__.py` likely wires the app factory, CORS, SQLAlchemy, and JWT-related setup.
   - The API surface is clearly domain-oriented rather than REST-for-everything; each route module maps to one major business area.

4. **Core data model**
   - `backend/app/models.py` is the architectural center of the backend.
   - The key entities are:
     - **User** for faculty, student, and admin identities
     - **Project** for research groups/initiatives
     - **ProjectMember** for membership and role within a project
     - **ProjectJoinRequest** for student/collaborator requests with notes and status
     - **Publication** for papers and metadata
     - **ActivityEvent** for platform audit/activity history
   - These models encode the main domain boundaries: identity, project collaboration, publication management, and platform activity.

5. **Authentication and authorization flow**
   - Authentication is **JWT-based** and stateless.
   - The auth subsystem handles registration, login, and the current-user lookup (`/me`), which the frontend uses to establish session context.
   - Authorization is role-driven at two levels:
     - **platform roles**: Faculty, Student, Admin
     - **project roles**: lead, collaborator, student
   - That split is important for the architecture: some permissions are global, while others are specific to a project membership.

6. **Project collaboration workflow**
   - Projects are not just records; they are collaboration spaces with membership state and request review.
   - Students can submit join requests with a note, leads can review pending requests, and leads can accept/decline them.
   - The system also supports **lead elevation** and a **guard against the last lead leaving**, which means the backend enforces membership invariants, not just UI rules.
   - The frontend `OrgChart` component visualizes this hierarchy as Lead → Collaborator → Student.

7. **Publications workflow**
   - Publications can be created manually or imported through **Crossref sync**.
   - The backend `publications` route and `tasks/publication_sync.py` indicate a split between synchronous CRUD and asynchronous enrichment/import logic.
   - The frontend separates “My Publications” from “Discover Community,” so publication data is used both for personal ownership and institution-wide browsing.

8. **Analytics and dashboard flow**
   - The dashboard is built around aggregated backend data rather than client-side calculation.
   - `backend/app/routes/dashboard.py` provides counts and chart-ready datasets such as publication trends and department comparisons.
   - The frontend consumes this data in `Charts.tsx`, which suggests the backend is responsible for shaping the analytics response into a directly renderable form.

9. **Background processing**
   - `backend/celery_worker.py`, `backend/app/celery_utils.py`, and `backend/app/tasks/publication_sync.py` show a separate async worker subsystem.
   - This is the architectural boundary for longer-running or external-API-bound work, especially publication synchronization against Crossref.
   - The worker is distinct from the Flask web process, so web requests stay responsive while sync jobs run out-of-band.

10. **Persistence and schema management**
   - The repository uses **SQLAlchemy** plus **Flask-Migrate/Alembic** for schema evolution.
   - There are migrations for the initial schema and later join-request changes, showing that the data model is actively versioned.
   - `seed.py` suggests a bootstrap path for local/demo data, while the runtime setup supports **SQLite locally** and **PostgreSQL in production**.

11. **Deployment topology**
   - The repo is split for deployment: **frontend on Vercel**, **backend on Render**, and **PostgreSQL on Render**.
   - `render.yaml` defines backend infrastructure, while `frontend/vercel.json` and the frontend env var point the browser app at the API origin.
   - The presence of CORS and separate frontend/backend URLs means the diagram should show two independently deployed services communicating over HTTP.

12. **What to draw as the main architecture**
   - Draw the browser-facing Next.js app as the presentation layer.
   - Draw the Flask API as the domain/service layer with route modules grouped by feature.
   - Place the database as the authoritative persistence layer behind SQLAlchemy.
   - Add a separate Celery worker for async publication sync.
   - Show Crossref as an external data source only for the publication-import path.

Main entry points: [`backend/app/__init__.py`](https://github.com/prahang/research-management-system/blob/master/backend/app/__init__.py) (App Setup), [`backend/app/models.py`](https://github.com/prahang/research-management-system/blob/master/backend/app/models.py) (Domain Models), [`backend/app/routes/projects.py`](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/projects.py) (Projects API), [`backend/app/routes/publications.py`](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/publications.py) (Publications API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>Next.js pages"]
  node_frontend_components["UI Components<br/>shared UI"]
  node_frontend_api["API Client<br/>fetch wrapper<br/>[api.ts]"]
  node_frontend_pages_projects["Projects Page<br/>screen<br/>[page.tsx]"]
  node_frontend_pages_publications["Publications Page<br/>screen<br/>[page.tsx]"]
  node_frontend_pages_users["Profile Page<br/>screen<br/>[page.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_app_init["App Setup<br/>flask factory<br/>[__init__.py]"]
  node_backend_routes_auth["Auth API<br/>route blueprint<br/>[auth.py]"]
  node_backend_routes_projects["Projects API<br/>route blueprint<br/>[projects.py]"]
  node_backend_routes_publications["Publications API<br/>route blueprint<br/>[publications.py]"]
  node_backend_routes_dashboard["Dashboard API<br/>route blueprint<br/>[dashboard.py]"]
  node_backend_routes_users["Users API<br/>route blueprint<br/>[users.py]"]
  node_backend_routes_search["Search API<br/>route blueprint<br/>[search.py]"]
  node_backend_models[("Domain Models<br/>SQLAlchemy models<br/>[models.py]")]
end

subgraph group_worker["Async Worker"]
  node_backend_tasks_publication_sync["Publication Sync<br/>celery task"]
  node_backend_celery_worker["Celery Worker<br/>worker process<br/>[celery_worker.py]"]
  node_backend_celery_utils["Celery Utils<br/>worker config<br/>[celery_utils.py]"]
end

subgraph group_data["Data Layer"]
  node_db_migrations["Migrations<br/>schema versioning"]
  node_db_seed["Seed Data<br/>bootstrap script<br/>[seed.py]"]
  node_postgres[("Database<br/>relational store")]
end

subgraph group_external["External"]
  node_crossref(("Crossref<br/>external metadata source"))
end

node_frontend_app -->|"uses UI"| node_frontend_components
node_frontend_app -->|"calls API"| node_frontend_api
node_frontend_pages_projects -->|"projects data"| node_backend_routes_projects
node_frontend_pages_publications -->|"publications data"| node_backend_routes_publications
node_frontend_pages_users -->|"profile data"| node_backend_routes_users
node_frontend_components -->|"charts"| node_backend_routes_dashboard
node_frontend_api -->|"HTTP"| node_backend_app_init
node_backend_app_init -->|"registers"| node_backend_routes_auth
node_backend_app_init -->|"registers"| node_backend_routes_projects
node_backend_app_init -->|"registers"| node_backend_routes_publications
node_backend_app_init -->|"registers"| node_backend_routes_dashboard
node_backend_app_init -->|"registers"| node_backend_routes_users
node_backend_app_init -->|"registers"| node_backend_routes_search
node_backend_routes_auth -->|"users"| node_backend_models
node_backend_routes_projects -->|"membership"| node_backend_models
node_backend_routes_publications -->|"publications"| node_backend_models
node_backend_routes_dashboard -->|"aggregates"| node_backend_models
node_backend_routes_users -->|"profiles"| node_backend_models
node_backend_routes_search -->|"searches"| node_backend_models
node_backend_tasks_publication_sync -->|"syncs"| node_crossref
node_backend_celery_worker -->|"executes"| node_backend_tasks_publication_sync
node_backend_celery_utils -->|"configures"| node_backend_tasks_publication_sync
node_backend_models -->|"persists"| node_postgres
node_db_migrations -->|"evolves"| node_postgres
node_db_seed -->|"loads"| node_postgres

click node_frontend_app "https://github.com/prahang/research-management-system/tree/master/frontend/src/app"
click node_frontend_components "https://github.com/prahang/research-management-system/tree/master/frontend/src/components"
click node_frontend_api "https://github.com/prahang/research-management-system/blob/master/frontend/src/lib/api.ts"
click node_frontend_pages_projects "https://github.com/prahang/research-management-system/blob/master/frontend/src/app/projects/page.tsx"
click node_frontend_pages_publications "https://github.com/prahang/research-management-system/blob/master/frontend/src/app/publications/page.tsx"
click node_frontend_pages_users "https://github.com/prahang/research-management-system/blob/master/frontend/src/app/users/[id]/page.tsx"
click node_backend_app_init "https://github.com/prahang/research-management-system/blob/master/backend/app/__init__.py"
click node_backend_routes_auth "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/auth.py"
click node_backend_routes_projects "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/projects.py"
click node_backend_routes_publications "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/publications.py"
click node_backend_routes_dashboard "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/dashboard.py"
click node_backend_routes_users "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/users.py"
click node_backend_routes_search "https://github.com/prahang/research-management-system/blob/master/backend/app/routes/search.py"
click node_backend_models "https://github.com/prahang/research-management-system/blob/master/backend/app/models.py"
click node_backend_tasks_publication_sync "https://github.com/prahang/research-management-system/blob/master/backend/app/tasks/publication_sync.py"
click node_backend_celery_worker "https://github.com/prahang/research-management-system/blob/master/backend/celery_worker.py"
click node_backend_celery_utils "https://github.com/prahang/research-management-system/blob/master/backend/app/celery_utils.py"
click node_db_migrations "https://github.com/prahang/research-management-system/tree/master/backend/migrations"
click node_db_seed "https://github.com/prahang/research-management-system/blob/master/backend/seed.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_components,node_frontend_api,node_frontend_pages_projects,node_frontend_pages_publications,node_frontend_pages_users toneBlue
class node_backend_app_init,node_backend_routes_auth,node_backend_routes_projects,node_backend_routes_publications,node_backend_routes_dashboard,node_backend_routes_users,node_backend_routes_search,node_backend_models toneAmber
class node_backend_tasks_publication_sync,node_backend_celery_worker,node_backend_celery_utils toneMint
class node_db_migrations,node_db_seed,node_postgres toneRose
class node_crossref toneIndigo
```

## Components

### Frontend

Next.js presentation and interaction layer

- [App Router](https://github.com/prahang/research-management-system/tree/master/frontend/src/app): Next.js pages · Browser entrypoint with routed screens for auth, projects, publications, and users. · `frontend/src/app`
- [UI Components](https://github.com/prahang/research-management-system/tree/master/frontend/src/components): shared UI · Reusable presentation pieces including charts, navigation, theme, and org chart views. · `frontend/src/components`
- [API Client](https://github.com/prahang/research-management-system/blob/master/frontend/src/lib/api.ts): fetch wrapper · Central browser-to-backend integration point used by the frontend. · `frontend/src/lib/api.ts`
- [Projects Page](https://github.com/prahang/research-management-system/blob/master/frontend/src/app/projects/page.tsx): screen · Frontend surface for project browsing and collaboration workflows. · `frontend/src/app/projects/page.tsx`
- [Publications Page](https://github.com/prahang/research-management-system/blob/master/frontend/src/app/publications/page.tsx): screen · Frontend surface for my publications and community discovery. · `frontend/src/app/publications/page.tsx`
- [Profile Page](https://github.com/prahang/research-management-system/blob/master/frontend/src/app/users/[id]/page.tsx): screen · Frontend surface for viewing individual user profiles. · `frontend/src/app/users/[id]/page.tsx`

### Backend

Flask API, domain logic, and persistence

- [App Setup](https://github.com/prahang/research-management-system/blob/master/backend/app/__init__.py): flask factory · Wires the Flask application, CORS, auth, and database setup. · `backend/app/__init__.py`
- [Auth API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/auth.py): route blueprint · Registration, login, and current-user session lookup. · `backend/app/routes/auth.py`
- [Projects API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/projects.py): route blueprint · Project membership, join requests, and role management. · `backend/app/routes/projects.py`
- [Publications API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/publications.py): route blueprint · CRUD and import-facing publication endpoints. · `backend/app/routes/publications.py`
- [Dashboard API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/dashboard.py): route blueprint · Aggregated counts and chart-ready analytics payloads. · `backend/app/routes/dashboard.py`
- [Users API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/users.py): route blueprint · User lookup and profile-related endpoints. · `backend/app/routes/users.py`
- [Search API](https://github.com/prahang/research-management-system/blob/master/backend/app/routes/search.py): route blueprint · Search endpoints for discovering records across the system. · `backend/app/routes/search.py`
- [Domain Models](https://github.com/prahang/research-management-system/blob/master/backend/app/models.py): SQLAlchemy models · Core entities for users, projects, memberships, join requests, publications, and activity history. · `backend/app/models.py`

### Async Worker

Background job processing for external sync

- [Publication Sync](https://github.com/prahang/research-management-system/blob/master/backend/app/tasks/publication_sync.py): celery task · Asynchronous Crossref import and publication enrichment workflow. · `backend/app/tasks/publication_sync.py`
- [Celery Worker](https://github.com/prahang/research-management-system/blob/master/backend/celery_worker.py): worker process · Separate process that executes background jobs out of band from HTTP requests. · `backend/celery_worker.py`
- [Celery Utils](https://github.com/prahang/research-management-system/blob/master/backend/app/celery_utils.py): worker config · Shared Celery configuration and task wiring helpers. · `backend/app/celery_utils.py`

### Data Layer

Database schema and migrations

- [Migrations](https://github.com/prahang/research-management-system/tree/master/backend/migrations): schema versioning · Alembic migration history for the relational schema. · `backend/migrations`
- [Seed Data](https://github.com/prahang/research-management-system/blob/master/backend/seed.py): bootstrap script · Local/demo data loading entrypoint. · `backend/seed.py`
- **Database**: relational store · Authoritative persistence for users, projects, publications, and activity.

### External

Outside systems integrated by the app

- **Crossref**: external metadata source · External publication metadata service used for sync/import.

## Connections

- App Router → UI Components: uses UI · Pages compose shared interface elements.
- App Router → API Client: calls API · Screens fetch and mutate data through the centralized client.
- Projects Page → Projects API: projects data · Project screens consume project collaboration endpoints.
- Publications Page → Publications API: publications data · Publication screens consume CRUD and discovery endpoints.
- Profile Page → Users API: profile data · Profile screens load user details from the API.
- UI Components → Dashboard API: charts · Chart components render backend-shaped analytics payloads.
- API Client → App Setup: HTTP · Browser client communicates with the Flask service over HTTP.
- App Setup → Auth API: registers · App factory mounts auth routes.
- App Setup → Projects API: registers · App factory mounts project routes.
- App Setup → Publications API: registers · App factory mounts publication routes.
- App Setup → Dashboard API: registers · App factory mounts dashboard routes.
- App Setup → Users API: registers · App factory mounts user routes.
- App Setup → Search API: registers · App factory mounts search routes.
- Auth API → Domain Models: users · Auth logic reads and writes user identity records.
- Projects API → Domain Models: membership · Project workflows depend on project, member, and join-request models.
- Publications API → Domain Models: publications · Publication endpoints persist and query publication entities.
- Dashboard API → Domain Models: aggregates · Dashboard metrics are derived from stored domain records.
- Users API → Domain Models: profiles · User endpoints read profile and role data.
- Search API → Domain Models: searches · Search spans the core persisted domain objects.
- Publication Sync → Crossref: syncs · Background job pulls publication metadata from Crossref.
- Celery Worker → Publication Sync: executes · Worker process runs publication sync tasks.
- Celery Utils → Publication Sync: configures · Shared Celery setup enables task execution.
- Domain Models → Database: persists · SQLAlchemy stores domain state in the relational database.
- Migrations → Database: evolves · Migrations version the database schema over time.
- Seed Data → Database: loads · Seed script populates initial or demo records.