Skip to main content

Architecture

:::tip Use this page when You want the system view behind Academia: how the frontend, backend, tenants, roles, infrastructure, and workflow rules connect so the rest of the documentation makes sense. :::

Academia is a split-platform system: a tenant-aware frontend for user experience and a modular backend API for business rules, data isolation, and workflow enforcement. The docs become much more useful when this split is explained clearly.

Fastest route through this guide​

If you want the quickest useful understanding, read these sections in order:

  1. Read System map for the high-level layers.
  2. Read Request and tenant flow for the most important runtime behavior.
  3. Read Role model to understand how permissions and dashboards shape the product.
  4. Read Workflow architecture to connect the technical structure to the academic operating flow.
  5. Continue to Local development or Environment and API client if you are implementing or integrating with the platform.

System map​

At a high level, Academia is organised into four layers:

  1. Public and authenticated frontend
  2. API and business logic backend
  3. Data and infrastructure services
  4. Operational flows that connect users, roles, and milestones

Frontend layer​

The frontend lives in kubsamelkamu/Academia and is built with a modern App Router stack.

Core technologies​

  • Next.js App Router
  • React + TypeScript
  • Tailwind CSS v4
  • shadcn/ui primitives
  • Zustand for UI and auth state
  • TanStack Query for server state
  • Axios for API access

Frontend responsibilities​

The frontend is responsible for:

  • public marketing and entry flows
  • authentication and role-aware routing
  • dashboard rendering by role
  • document, project, and milestone interaction surfaces
  • coordinator, advisor, evaluator, and student workspaces
  • tenant-aware request forwarding and API consumption

Frontend structure​

The current repo structure is centred around the App Router and feature-driven UI composition:

src/
  app/                  App Router pages and route groups
    (auth)/             login, register, onboarding
    (marketing)/        landing and public marketing pages
    dashboard/          authenticated role-based views
    api/                Next.js route handlers when needed
  components/
    ui/                 shared primitives
    layout/             shell, header, footer, sidebar
    dashboard/          feature and role components
  config/               navigation and app configuration
  lib/api/              axios client and API modules
  store/                Zustand state
  types/                shared frontend types

Backend layer​

The backend lives in kubsamelkamu/academia-backend-api and provides the workflow engine behind the platform.

Core technologies​

  • NestJS
  • TypeScript
  • PostgreSQL
  • Prisma ORM
  • Redis and queue processing
  • Passport + JWT
  • Socket.IO gateways

Backend responsibilities​

The backend is responsible for:

  • authentication and RBAC enforcement
  • tenant resolution and data isolation
  • project lifecycle rules
  • milestone and template management
  • evaluation workflows and scoring rules
  • notifications, analytics, and background jobs
  • storage-backed document handling and activity flows

Backend structure​

The repository follows a modular NestJS layout:

src/
  common/               shared guards, decorators, pipes, interceptors
  config/               environment and app configuration
  core/                 infrastructure services, cache, database, queue
  modules/
    auth/
    tenant/
    project/
    milestone/
    evaluation/
    notification/
    analytics/
    communication/
    department/
    subscription/
    user/
  prisma/               schema, migrations, seeds

Request and tenant flow​

One of the most important parts of the architecture is how tenant context moves through the system.

Frontend side​

  • The frontend derives tenant context from the current host.
  • Middleware forwards tenant identity for internal app behavior.
  • The API client attaches auth and tenant headers where required.
  • Role-based navigation and dashboard shells are resolved in the UI.

Backend side​

  • The backend resolves the tenant per request.
  • Guards and role checks enforce access boundaries.
  • Feature modules apply tenant-scoped business rules.
  • Queries and mutations operate inside the right institutional boundary.

This is why the docs should describe flows, not just screens. A dashboard page only makes sense when its tenant, role, and workflow rules are understood.

Role model​

The platform is organised around role-specific workspaces rather than a single generic dashboard.

Core roles​

  • Department heads
  • Coordinators
  • Advisors
  • Students
  • Evaluators

Architectural implication​

Each role influences:

  • which routes appear in navigation
  • which API endpoints are available
  • which queue items and metrics are visible
  • which actions can affect project state
  • which documents, schedules, and evaluations can be edited or reviewed

Workflow architecture​

Academia is best understood as a connected workflow system.

Stage 1: Setup​

  • create tenant and department context
  • register users and define role access
  • configure templates, milestones, and workflow defaults

Stage 2: Delivery​

  • submit project proposals
  • manage project groups and documents
  • move through milestone-driven academic work
  • exchange advisor feedback and updates

Stage 3: Review and defense​

  • schedule evaluations and defense sessions
  • review documents and project outputs
  • track analytics and operational health
  • notify stakeholders of deadlines and outcomes

Data and infrastructure​

The main operational dependencies behind the platform are:

  • PostgreSQL for application data
  • Prisma for schema and persistence access
  • Redis for cache and queue-backed workflows
  • JWT for session and request authentication
  • Queue processing for notifications and background operations
  • Realtime channels for collaboration and live updates

Documentation implication​

This architecture suggests how the docs should grow next:

  • user-facing docs should be organised around roles and workflows
  • contributor docs should explain tenant, auth, and API behavior clearly
  • architecture docs should connect frontend routes to backend modules
  • screenshots should support pages where UI context matters for trust and clarity

Best page after this one​

If you want to do next...Go hereWhy
Start using the platform in the correct orderOnboarding and first setupIt turns the architecture into the real first-run setup sequence.
Understand the day-to-day operating modelProject lifecycleIt shows how proposals, milestones, evaluation, and defense run across the system.
Understand role ownership in the product UIRoles and dashboardsIt maps architecture decisions to role-based workspaces and responsibilities.
Prepare local integration or development workLocal developmentIt is the next practical step after understanding the system layout.

Best next reads​