Skip to main content

sidebar_position: 1 title: Environment and API client description: Environment variables, shared Axios client behavior, auth flow, and API integration rules for the Academia frontend.

Environment and API client

The Academia UI is a frontend that depends on a deployed API. The current Next.js app uses environment variables, a shared Axios client, tenant-aware headers, and a few same-origin proxy routes to keep integration behavior consistent.

Fastest route through this guide​

  1. Start with Required environment variables if you are setting up a local or deployed frontend.
  2. Read How the shared API client behaves if you need the exact request and response rules.
  3. Jump to Auth and tenant context if login or tenant routing is the main concern.
  4. Use Practical endpoint families when you are looking for the main backend areas the UI already calls.

Required environment variables​

The frontend README currently describes these environment variables as the main integration surface:

NEXT_PUBLIC_API_BASE_URL="https://api.academia.et/api/v1"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_ACADEMIA_MOCK_ROLE="coordinator"

NEXT_PUBLIC_API_BASE_URL​

This is the most important one. The shared Axios client expects the value to already include /api/v1.

Examples:

NEXT_PUBLIC_API_BASE_URL="http://localhost:3001/api/v1"
NEXT_PUBLIC_API_BASE_URL="https://api.academia.et/api/v1"

Because /api/v1 is already included, frontend API modules call routes such as /auth/login, /tenant/current, or /project-groups/me without repeating the version prefix.

NEXT_PUBLIC_APP_URL​

This is useful for local app URL awareness and deployment-level integration, especially when frontend-generated links or route-aware features need a stable app origin.

NEXT_PUBLIC_ACADEMIA_MOCK_ROLE​

This is optional and mainly helpful for local UI previews. The README lists role values such as:

  • department_head
  • coordinator
  • advisor
  • evaluator
  • student
  • department_committee

Use it only for preview or isolated UI work. Real workflow verification should still happen against authenticated backend data.

How the shared API client behaves​

The frontend centralizes backend communication in src/lib/api/client.ts in the upstream Academia repository.

Base URL and defaults​

The client currently:

  • uses NEXT_PUBLIC_API_BASE_URL as the Axios baseURL
  • falls back to http://localhost:3001/api/v1 when the env var is missing
  • sets Content-Type: application/json by default
  • enables withCredentials: true

This means local development can still work with the default backend port, but production or multi-environment deployments should set the env var explicitly.

Request interceptor rules​

On the browser side, the request interceptor reads auth state and adds the headers the backend expects.

Current behavior includes:

  • Authorization: Bearer <accessToken> when a token exists
  • X-Tenant-Domain: <tenantDomain> when tenant context exists
  • fallback lookup of tenantDomain from persisted auth-storage in local storage if the in-memory store is empty

This is why feature-specific API modules stay simple. They call apiClient.get(...) or apiClient.post(...), and the shared client injects auth and tenant context automatically.

Response interceptor rules​

The response interceptor also normalizes backend responses.

Current behavior includes:

  • unwrapping the backend success envelope from { success, message, data, timestamp } into response.data
  • flattening backend error envelopes into a clear error.message
  • converting throttling and 429 behavior into the normalized message Too many requests. Try again later.
  • treating 401 as a dead session only for selected identity-sensitive routes instead of logging users out on every unauthorized response

That last rule matters because the frontend intentionally avoids random logout behavior when a partially wired feature returns 401.

Auth and tenant context​

The current auth store is more than a token holder. It also preserves tenant routing context and canonical user information.

Login flow​

The frontend login flow posts to:

POST /auth/login

with a payload that may include:

{
	"email": "depthead@university.edu",
	"password": "YourPassword",
	"tenantDomain": "addisababauniversity6"
}

The auth store currently:

  • includes tenantDomain from the form or the previously stored auth state
  • stores accessToken, refreshToken, user, and tenantDomain after login
  • follows login with /auth/me as a best-effort canonical refresh of the current user profile

Session profile shape​

The backend GET /auth/me response already includes tenant-aware user data such as:

  • tenantId
  • tenantDomain
  • tenant object with id, name, domain, and status
  • departmentId and department information
  • roles
  • optional tenantVerification state for department-head-first flows

This matters because both dashboard routing and tenant-aware API behavior depend on the current user carrying the right tenant context.

Same-origin proxy routes in Next.js​

The frontend does not send every request directly to the backend. A few public or cross-origin-sensitive flows are proxied through Next.js route handlers.

Current examples in the frontend repo include:

  • /api/invitations/accept/preview
  • /api/invitations/accept
  • /api/contact

These handlers use NEXT_PUBLIC_API_BASE_URL server-side, forward JSON payloads upstream, and return the upstream status and payload back to the client.

This pattern is useful when:

  • the flow is public and should avoid browser-side CORS issues
  • the frontend wants a stable same-origin route for form submission
  • you need server-side control of request forwarding without exposing more client complexity

Realtime and derived origins​

Not every integration goes through REST alone. The current frontend also derives a socket origin from NEXT_PUBLIC_API_BASE_URL for realtime features.

Current examples include:

  • notifications socket integration
  • chat socket integration

The socket helpers derive the origin from the API base URL and authenticate using:

  • accessToken
  • tenantDomain

This keeps realtime features aligned with the same auth and tenant context used by the Axios client.

Practical endpoint families​

The UI already spans several backend areas. These are the main families contributors should recognize first.

Auth and identity​

  • POST /auth/login
  • GET /auth/me
  • GET /auth/profile

Tenant and department management​

  • GET /tenant/current
  • PATCH /tenant/address
  • POST /tenant/verification/document
  • GET /tenant/users
  • GET /tenant/users/paged
  • PUT /tenant/users/:id
  • DELETE /tenant/users/:id
  • PATCH /tenant/users/:id/reactivate
  • GET /tenant/invitations
  • POST /tenant/invitations
  • POST /tenant/invitations/:id/resend

Student group formation​

  • POST /group-leader-requests
  • GET /group-leader-requests/me
  • POST /project-groups
  • GET /project-groups/me
  • POST /project-groups/:groupId/join-requests
  • POST /project-groups/me/submit
  • GET /project-groups/review/submitted
  • POST /project-groups/review/:groupId/approve
  • POST /project-groups/review/:groupId/reject

Proposal and project work​

  • POST /projects/proposals
  • POST /projects/proposals/with-proposal-pdf
  • GET /projects/proposals/group
  • PUT /projects/proposals/:id/status
  • PUT /projects/proposals/:id/advisor
  • GET /projects
  • GET /projects/:id

Milestones and advisor review​

  • GET /projects/advisors/me
  • GET /projects/advisors/me/projects
  • GET /projects/advisors/me/milestone-review-queue
  • GET /projects/milestones/:id/submissions
  • PUT /projects/milestones/:id/submissions/:submissionId/approve

Notifications and push​

  • GET /notifications/push/vapid-public-key
  • push subscription endpoints under /notifications/push
  • proposal and group-review notifications emitted by backend services

Integration rules contributors should keep consistent​

  • Keep NEXT_PUBLIC_API_BASE_URL versioned with /api/v1; do not duplicate the prefix in feature modules.
  • Use the shared Axios client instead of ad hoc fetch for authenticated app routes so auth and tenant headers are injected consistently.
  • Use same-origin Next.js proxy handlers when a public flow would otherwise create browser-side CORS or token-handling problems.
  • Document endpoint families and behavior, not secrets or real tokens.
  • Treat tenant context as part of every request model, not as an optional afterthought.

Best next reads​

:::note Security Never commit real tokens or production secrets. Document variable names, allowed values, and purpose. Keep real credentials in local env files, deployment settings, or secret stores. :::