feat: enhance onboarding process and company profile management

- Updated CompanyInfoResponseDto to include company profile data in response.
- Enhanced ResponseExternalProfileDto to include active profile type and onboarding details.
- Added new fields to ExternalProfile entity for active profile type and onboarding status.
- Implemented onboarding wizard dialog in the frontend to guide users through the onboarding process.
- Introduced API endpoints for managing company profiles and onboarding steps.
- Created migrations to add new columns for active mode and onboarding status in the database.
- Added functionality to switch between operational modes (importer/exporter) and create profiles as needed.
- Improved user experience by ensuring onboarding is enforced for new users and those without completed profiles.

apps/edr-freight-api/src/modules/companies/companies.controller.ts

@@ -24,6 +24,9 @@ import { UpdateCompanyDto } from "./dto/update-company.dto";
 import { CreateExternalProfileDto } from "./dto/create-external-profile.dto";
 import { CreateCompanyWithProfileDto } from "./dto/create-company-with-profile.dto";
 import { AddCompanyProfilesDto } from "./dto/add-company-profiles.dto";
+import { CreateCompanyProfileDto } from "./dto/create-company-profile.dto";
+import { SetActiveModeDto } from "./dto/set-active-mode.dto";
+import { SetOnboardingStepDto } from "./dto/set-onboarding-step.dto";
 import {
   ResponseCompanyDto,
   ResponseCompanyProfileDto,
@@ -105,6 +108,58 @@ export class CompaniesController {
     return profiles.map((p) => new ResponseCompanyProfileDto(p));
   }
 
+  @Post("company-profile")
+  @ApiOperation({
+    summary:
+      "Create a single operational profile for the current user's company and make it the active mode",
+  })
+  async createCompanyProfile(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: CreateCompanyProfileDto,
+  ): Promise<ResponseCompanyProfileDto> {
+    const profile = await this.companiesService.createCompanyProfileForUser(
+      user.id,
+      dto.type,
+      dto.businessLicense,
+    );
+    return new ResponseCompanyProfileDto(profile);
+  }
+
+  @Patch("active-mode")
+  @ApiOperation({
+    summary: "Switch the current user's active operational mode (importer/exporter)",
+  })
+  async setActiveMode(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: SetActiveModeDto,
+  ): Promise<CompanyInfoResponseDto> {
+    const { profile, company } = await this.companiesService.setActiveMode(
+      user.id,
+      dto.type,
+    );
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
+  @Patch("onboarding-step")
+  @ApiOperation({ summary: "Persist the user's current onboarding wizard step" })
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async setOnboardingStep(
+    @CurrentUser() user: CurrentIamUser,
+    @Body() dto: SetOnboardingStepDto,
+  ): Promise<void> {
+    await this.companiesService.setOnboardingStep(user.id, dto.step);
+  }
+
+  @Post("onboarding/complete")
+  @ApiOperation({ summary: "Mark the current user's onboarding as complete" })
+  async completeOnboarding(
+    @CurrentUser() user: CurrentIamUser,
+  ): Promise<CompanyInfoResponseDto> {
+    const { profile, company } =
+      await this.companiesService.markOnboardingComplete(user.id);
+    return new CompanyInfoResponseDto(profile, company);
+  }
+
   // Used by portal
   @Post("create")
   @ApiOperation({

apps/edr-freight-api/src/modules/companies/companies.service.ts

@@ -81,6 +81,18 @@ export class CompaniesService {
       attributes: dto.attributes ?? null,
     });
 
+    // Default active mode from the chosen role(s): importer wins when both are
+    // picked, otherwise the first allowed type chosen.
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    const chosenTypes = (dto.companyProfiles ?? [])
+      .map((p) => p.type)
+      .filter((t) => allowedTypes.includes(t));
+    const activeProfileType =
+      chosenTypes.find((t) => t === ProfileType.importer) ??
+      chosenTypes[0] ??
+      allowedTypes[0] ??
+      null;
+
     const profile = await this.profilesRepo.create({
       userId: identity.userId,
       companyId: company.id,
@@ -90,6 +102,8 @@ export class CompaniesService {
       phone: identity.phone,
       jobTitle: dto.jobTitle ?? null,
       isPrimaryContact: dto.isPrimaryContact ?? true,
+      activeProfileType,
+      onboardingStep: 'company',
     });
 
     // Persist the operational role(s) chosen during onboarding. Types are
@@ -174,6 +188,18 @@ export class CompaniesService {
     const companyId = profile?.company?.id ?? profile?.companyId ?? null;
     if (!companyId) return this.emptyDashboardSummary();
 
+    // Scope KPIs to the active operational profile (importer/exporter mode) when
+    // one resolves; otherwise aggregate across the whole company.
+    const companyProfileId = profile?.activeProfileType
+      ? ((await this.companyProfilesRepo.findByType(
+          companyId,
+          profile.activeProfileType,
+        )) ?? null)
+      : null;
+    const scope = companyProfileId
+      ? { companyProfileId: companyProfileId.id }
+      : { companyId };
+
     const now = new Date();
     const yearStart = new Date(now.getFullYear(), 0, 1);
     const prevYearStart = new Date(now.getFullYear() - 1, 0, 1);
@@ -191,22 +217,22 @@ export class CompaniesService {
       tonnagePrev,
       monthlyRows,
     ] = await Promise.all([
-      this.dashboardRepo.countDelivered(companyId, yearStart, now),
-      this.dashboardRepo.countCommitted(companyId, yearStart, now),
-      this.dashboardRepo.sumPaidSpendByCurrency(companyId, yearStart, now),
+      this.dashboardRepo.countDelivered(scope, yearStart, now),
+      this.dashboardRepo.countCommitted(scope, yearStart, now),
+      this.dashboardRepo.sumPaidSpendByCurrency(scope, yearStart, now),
       this.dashboardRepo.sumPaidSpendByCurrency(
-        companyId,
+        scope,
         prevYearStart,
         prevYearToDate,
       ),
-      this.dashboardRepo.sumCommittedTonnage(companyId, yearStart, now),
+      this.dashboardRepo.sumCommittedTonnage(scope, yearStart, now),
       this.dashboardRepo.sumCommittedTonnage(
-        companyId,
+        scope,
         prevYearStart,
         prevYearToDate,
       ),
       this.dashboardRepo.monthlyCommittedTonnage(
-        companyId,
+        scope,
         this.monthsAgo(now, 5),
         now,
       ),
@@ -505,4 +531,145 @@ export class CompaniesService {
 
     return this.companyProfilesRepo.findByCompanyId(companyId);
   }
+
+  /**
+   * Create a single operational profile for the current user's company and
+   * make it the active mode in the same call. Powers the header "Switch to
+   * Exporter/Importer" flow when the target profile doesn't exist yet.
+   */
+  async createCompanyProfileForUser(
+    userId: string,
+    type: ProfileType,
+    businessLicense?: string,
+  ): Promise<CompanyProfile> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.findCompanyById(companyId);
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    if (!allowedTypes.includes(type)) {
+      throw new BadRequestException(
+        `Profile type "${type}" is not allowed for company type "${company.type}"`,
+      );
+    }
+
+    let created = await this.companyProfilesRepo.findByType(companyId, type);
+    if (!created) {
+      const reference = await this.companyProfilesRepo.generateReference(type);
+      created = await this.companyProfilesRepo.create({
+        companyId,
+        type,
+        reference,
+        businessLicense: businessLicense ?? null,
+        status: ProfileStatus.Active,
+      });
+    }
+
+    await this.profilesRepo.update(profile.id, { activeProfileType: type });
+
+    return created;
+  }
+
+  /**
+   * Switch the user's active operational mode. The target profile must already
+   * exist — clients create it first via createCompanyProfileForUser.
+   */
+  async setActiveMode(
+    userId: string,
+    type: ProfileType,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+
+    const companyId = profile.company?.id ?? profile.companyId;
+    const company = await this.findCompanyById(companyId);
+
+    const allowedTypes = this.getProfileTypeForCompanyType(company.type);
+    if (!allowedTypes.includes(type)) {
+      throw new BadRequestException(
+        `Profile type "${type}" is not allowed for company type "${company.type}"`,
+      );
+    }
+
+    const existing = await this.companyProfilesRepo.findByType(companyId, type);
+    if (!existing) {
+      throw new ConflictException(
+        `No ${type} profile exists yet — create it before switching`,
+      );
+    }
+
+    await this.profilesRepo.update(profile.id, { activeProfileType: type });
+
+    return this.getCompanyInfoByUserId(userId);
+  }
+
+  async setOnboardingStep(userId: string, step: string): Promise<void> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+    await this.profilesRepo.update(profile.id, { onboardingStep: step });
+  }
+
+  async markOnboardingComplete(
+    userId: string,
+  ): Promise<{ profile: ExternalProfile; company: Company }> {
+    const profile = await this.profilesRepo.findByUserId(userId);
+    if (!profile)
+      throw new NotFoundException(`Profile for user ${userId} not found`);
+    await this.profilesRepo.update(profile.id, {
+      onboardingCompleted: true,
+      onboardingStep: 'done',
+    });
+    return this.getCompanyInfoByUserId(userId);
+  }
+
+  /**
+   * Resolve which company_profile a new booking belongs to, from the company
+   * and the booking's trade direction. IMPORT → importer profile, EXPORT →
+   * exporter profile; for DOMESTIC or a forwarder/single-profile company (or
+   * when the natural profile doesn't exist) it falls back to the user's active
+   * profile, then the company's first profile. Returns null when the company
+   * has no profiles at all.
+   */
+  async resolveCompanyProfileIdForBooking(
+    companyId: string,
+    tradeDirection: string,
+    fallbackType?: ProfileType | null,
+  ): Promise<string | null> {
+    const profiles = await this.companyProfilesRepo.findByCompanyId(companyId);
+    if (profiles.length === 0) return null;
+
+    const naturalType =
+      tradeDirection === 'IMPORT'
+        ? ProfileType.importer
+        : tradeDirection === 'EXPORT'
+          ? ProfileType.exporter
+          : null;
+
+    const byType = (type?: ProfileType | null) =>
+      type ? profiles.find((p) => p.type === type) : undefined;
+
+    const match = byType(naturalType) ?? byType(fallbackType) ?? profiles[0];
+    return match?.id ?? null;
+  }
+
+  /**
+   * Resolve the company_profile a customer's data should be scoped to, from
+   * their persisted active mode. Returns null when nothing can be resolved
+   * (not onboarded yet) so callers can fall back to company-level scoping.
+   */
+  async resolveActiveCompanyProfileId(userId: string): Promise<string | null> {
+    try {
+      const { profile, company } = await this.getCompanyInfoByUserId(userId);
+      const type = profile.activeProfileType;
+      if (!type) return null;
+      const match = company.companyProfiles?.find((p) => p.type === type);
+      return match?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
 }

apps/edr-freight-api/src/modules/companies/company-dashboard.repository.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { Repository, SelectQueryBuilder } from 'typeorm';
 
 import { Booking } from '../bookings/entities/booking.entity';
 
@@ -31,6 +31,27 @@ export interface CurrencyTotal {
   total: number;
 }
 
+/**
+ * What the dashboard is scoped to: a single operational profile (the active
+ * importer/exporter mode) when one resolves, otherwise the whole company
+ * (legacy / not-yet-onboarded fallback).
+ */
+export type DashboardScope =
+  | { companyProfileId: string }
+  | { companyId: string };
+
+/** Apply the scope as a WHERE clause on a bookings query builder. */
+function applyScope(
+  qb: SelectQueryBuilder<Booking>,
+  scope: DashboardScope,
+): SelectQueryBuilder<Booking> {
+  return 'companyProfileId' in scope
+    ? qb.where('b.company_profile_id = :companyProfileId', {
+        companyProfileId: scope.companyProfileId,
+      })
+    : qb.where('b.company_id = :companyId', { companyId: scope.companyId });
+}
+
 export interface MonthlyTonnage {
   year: number;
   month: number; // 1-12
@@ -50,35 +71,33 @@ export class CompanyDashboardRepository {
     private readonly bookings: Repository<Booking>,
   ) {}
 
-  /** Count of delivered/completed bookings for a company within [from, to). */
-  async countDelivered(companyId: string, from: Date, to: Date): Promise<number> {
-    return this.bookings
-      .createQueryBuilder('b')
-      .where('b.company_id = :companyId', { companyId })
+  /** Count of delivered/completed bookings within [from, to) for the scope. */
+  async countDelivered(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    return applyScope(this.bookings.createQueryBuilder('b'), scope)
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...DELIVERED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
       .getCount();
   }
 
-  /** Count of committed (non-draft, non-dead) bookings for a company within [from, to). */
-  async countCommitted(companyId: string, from: Date, to: Date): Promise<number> {
-    return this.bookings
-      .createQueryBuilder('b')
-      .where('b.company_id = :companyId', { companyId })
+  /** Count of committed (non-draft, non-dead) bookings within [from, to) for the scope. */
+  async countCommitted(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    return applyScope(this.bookings.createQueryBuilder('b'), scope)
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
       .getCount();
   }
 
-  /** Sum of paid booking totals, grouped by currency, within [from, to). */
-  async sumPaidSpendByCurrency(companyId: string, from: Date, to: Date): Promise<CurrencyTotal[]> {
-    const rows = await this.bookings
-      .createQueryBuilder('b')
-      .select('b.payment_currency', 'currency')
-      .addSelect('COALESCE(SUM(b.total_amount), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Sum of paid booking totals, grouped by currency, within [from, to) for the scope. */
+  async sumPaidSpendByCurrency(scope: DashboardScope, from: Date, to: Date): Promise<CurrencyTotal[]> {
+    const rows = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('b.payment_currency', 'currency')
+        .addSelect('COALESCE(SUM(b.total_amount), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere("b.payment_status = 'PAID'")
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
@@ -88,12 +107,14 @@ export class CompanyDashboardRepository {
     return rows.map((r) => ({ currency: r.currency ?? 'ETB', total: Number(r.total) }));
   }
 
-  /** Total committed tonnage (cargo VGM) for a company within [from, to). */
-  async sumCommittedTonnage(companyId: string, from: Date, to: Date): Promise<number> {
-    const row = await this.bookings
-      .createQueryBuilder('b')
-      .select('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Total committed tonnage (cargo VGM) within [from, to) for the scope. */
+  async sumCommittedTonnage(scope: DashboardScope, from: Date, to: Date): Promise<number> {
+    const row = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })
@@ -102,14 +123,16 @@ export class CompanyDashboardRepository {
     return Number(row?.total ?? 0);
   }
 
-  /** Committed tonnage grouped by calendar month within [from, to). */
-  async monthlyCommittedTonnage(companyId: string, from: Date, to: Date): Promise<MonthlyTonnage[]> {
-    const rows = await this.bookings
-      .createQueryBuilder('b')
-      .select('EXTRACT(YEAR FROM b.created_at)', 'year')
-      .addSelect('EXTRACT(MONTH FROM b.created_at)', 'month')
-      .addSelect('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total')
-      .where('b.company_id = :companyId', { companyId })
+  /** Committed tonnage grouped by calendar month within [from, to) for the scope. */
+  async monthlyCommittedTonnage(scope: DashboardScope, from: Date, to: Date): Promise<MonthlyTonnage[]> {
+    const rows = await applyScope(
+      this.bookings
+        .createQueryBuilder('b')
+        .select('EXTRACT(YEAR FROM b.created_at)', 'year')
+        .addSelect('EXTRACT(MONTH FROM b.created_at)', 'month')
+        .addSelect('COALESCE(SUM(b.cargo_total_weight_vgm), 0)', 'total'),
+      scope,
+    )
       .andWhere('b.deleted_at IS NULL')
       .andWhere('b.status IN (:...statuses)', { statuses: [...COMMITTED_STATUSES] })
       .andWhere('b.created_at >= :from AND b.created_at < :to', { from, to })

apps/edr-freight-api/src/modules/companies/dto/company-info-response.dto.ts

@@ -8,7 +8,7 @@ export class CompanyInfoResponseDto {
   company: ResponseCompanyDto;
 
   constructor(profile: ExternalProfile, company: Company) {
-    this.profile = new ResponseExternalProfileDto(profile);
+    this.profile = new ResponseExternalProfileDto(profile, company);
     this.company = new ResponseCompanyDto(company);
   }
 }

apps/edr-freight-api/src/modules/companies/dto/create-company-profile.dto.ts

@@ -0,0 +1,12 @@
+import { IsEnum, IsOptional, IsString, MaxLength } from 'class-validator';
+import { ProfileType } from '../entities/company-profile.entity';
+
+export class CreateCompanyProfileDto {
+  @IsEnum(ProfileType)
+  type!: ProfileType;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  businessLicense?: string;
+}

apps/edr-freight-api/src/modules/companies/dto/response-external-profile.dto.ts

@@ -1,4 +1,8 @@
-import { ExternalProfile } from '../entities/external-profile.entity';
+import { Company } from '../entities/company.entity';
+import {
+  ExternalProfile,
+} from '../entities/external-profile.entity';
+import { ProfileType } from '../entities/company-profile.entity';
 
 export class ResponseExternalProfileDto {
   id: string;
@@ -11,10 +15,20 @@ export class ResponseExternalProfileDto {
   nationalId?: string | null;
   jobTitle?: string | null;
   isPrimaryContact: boolean;
+  /** The active operational mode (importer/exporter/forwarder). */
+  activeProfileType?: ProfileType | null;
+  /**
+   * The id of the company_profile matching activeProfileType, resolved
+   * server-side so the client never re-derives it. Null until a company
+   * (with profiles) is loaded and a matching profile exists.
+   */
+  activeCompanyProfileId?: string | null;
+  onboardingStep?: string | null;
+  onboardingCompleted: boolean;
   createdAt: Date;
   updatedAt: Date;
 
-  constructor(profile: ExternalProfile) {
+  constructor(profile: ExternalProfile, company?: Company) {
     this.id = profile.id;
     this.userId = profile.userId;
     this.companyId = profile.companyId;
@@ -25,6 +39,13 @@ export class ResponseExternalProfileDto {
     this.nationalId = profile.nationalId;
     this.jobTitle = profile.jobTitle;
     this.isPrimaryContact = profile.isPrimaryContact;
+    this.activeProfileType = profile.activeProfileType ?? null;
+    this.onboardingStep = profile.onboardingStep ?? null;
+    this.onboardingCompleted = profile.onboardingCompleted ?? false;
+    this.activeCompanyProfileId =
+      company?.companyProfiles?.find(
+        (p) => p.type === profile.activeProfileType,
+      )?.id ?? null;
     this.createdAt = profile.createdAt;
     this.updatedAt = profile.updatedAt;
   }

apps/edr-freight-api/src/modules/companies/dto/set-active-mode.dto.ts

@@ -0,0 +1,7 @@
+import { IsEnum } from 'class-validator';
+import { ProfileType } from '../entities/company-profile.entity';
+
+export class SetActiveModeDto {
+  @IsEnum(ProfileType)
+  type!: ProfileType;
+}

apps/edr-freight-api/src/modules/companies/dto/set-onboarding-step.dto.ts

@@ -0,0 +1,7 @@
+import { IsString, MaxLength } from 'class-validator';
+
+export class SetOnboardingStepDto {
+  @IsString()
+  @MaxLength(40)
+  step!: string;
+}

apps/edr-freight-api/src/modules/companies/entities/external-profile.entity.ts

@@ -1,6 +1,7 @@
 import { BaseEntity } from '@edr/api-common';
 import { Column, Entity, Index, ManyToOne, JoinColumn } from 'typeorm';
 import { Company } from './company.entity';
+import { ProfileType } from './company-profile.entity';
 
 @Entity({ schema: 'freight', name: 'external_profiles' })
 @Index(['userId'])
@@ -36,4 +37,31 @@ export class ExternalProfile extends BaseEntity {
 
   @Column({ name: 'is_primary_contact', type: 'boolean', default: false })
   isPrimaryContact!: boolean;
+
+  /**
+   * The operational profile the user is currently "in" (importer vs exporter,
+   * or the single forwarder profile). Drives header switching and scopes the
+   * customer's bookings / dashboard to that company_profile. Nullable for
+   * users who haven't picked a role yet.
+   */
+  @Column({
+    name: 'active_profile_type',
+    type: 'varchar',
+    length: 32,
+    nullable: true,
+    enum: ProfileType,
+  })
+  activeProfileType?: ProfileType | null;
+
+  /** Coarse resume point for the onboarding wizard (e.g. 'role', 'company', 'documents', 'done'). */
+  @Column({
+    name: 'onboarding_step',
+    type: 'varchar',
+    length: 40,
+    nullable: true,
+  })
+  onboardingStep?: string | null;
+
+  @Column({ name: 'onboarding_completed', type: 'boolean', default: false })
+  onboardingCompleted!: boolean;
 }