How oxtron-mx/oxtron-1 works
1. What this repo is
- A Next.js App Router application for carbon/emissions management: users measure emissions across business activities, generate and communicate reports, and administer company/user settings.
- The structure strongly suggests a multi-tenant, authenticated SaaS dashboard with localization and role/permission-aware access.
2. Top-level route architecture
- The application is organized under app/[lang], so locale is part of the URL and the whole UI is rendered per language.
- There are two broad route families:
- Public/auth routes: login/register/forgot-password/update-password/register-success/no-access.
- Protected dashboard routes under app/[lang]/dashboard, which are the core product UI.
3. Dashboard shell and layout boundaries
- app/[lang]/dashboard/layout.tsx, dashboard-layout-client.tsx, and auth-wrapper.tsx form the authenticated shell around all business pages.
- This shell likely handles navigation, session checks, and layout state before rendering feature pages.
- middleware.ts is an important boundary for request-time routing/auth/locale enforcement.
4. Core product areas
- The dashboard is split into three major functional domains:
- Measure: capture activity data and calculate emissions.
- Communicate: create and deliver environmental reports.
- Settings: manage company profile, users, language, FAQs, glossary, tutorials, report parameters, and plan/account settings.
- app/[lang]/dashboard/page.tsx and capture/page.tsx appear to be entry points for the main workflow.
5. Measurement workflow
- app/[lang]/dashboard/measure/* contains the emissions data-entry flows for specific categories:
- commuting, facilities, logistics, manufacturing, travels, vehicles.
- Each category has:
- a listing page,
- an "[id]" detail page,
- and form components under components/forms/measure/....
- This indicates a master-detail workflow: user selects a measurement record, edits it, and possibly adds invoices or supporting details.
6. Supporting measurement detail layer
- The components/forms/measure/Details/* forms imply a second-step detail capture layer for invoices, custom emission factors, and other measurement metadata.
- constants/emission-factors.ts, store/shared/combos/*, and hooks/measure/* suggest the UI is driven by standardized emission factor catalogs and status enumerations.
- The store/measure/* and actions/measure/* folders show feature-specific state/actions separated by domain, which helps keep each measurement type isolated.
7. Reporting and communication
- app/[lang]/dashboard/communicate/* and components/forms/communicate/CreateReport.tsx drive report generation.
- components/communicate/EnvironmentalReport.tsx and report.tsx are responsible for report presentation.
- app/api/reports/[reportId]/[format]/route.ts is the key backend boundary for exporting/downloading reports in multiple formats.
- utils/download-report.ts likely encapsulates the client-side download flow.
8. Settings and administration
- The settings area is broad and operational, not just cosmetic:
- company setup/info,
- admin account management,
- user accounts,
- permissions,
- report parameters,
- language switching,
- FAQs/tutorials/glossary,
- plan upgrade.
- Components under components/forms/settings/*, components/setup/*, and components/admin/* indicate a management console for organization-level configuration.
9. Authentication, authorization, and session handling
- Authentication is built around NextAuth:
- app/api/auth/[...nextauth]/route.ts
- auth.ts
- auth.config.ts
- types/next-auth.d.ts
- Access control is enforced with shared helpers and UI guards:
- components/shared/ProtectedRoute.tsx
- components/shared/CanAccess.tsx
- hooks/auth/useCurrentUser.ts
- hooks/auth/usePermissions.ts
- utils/auth-helpers.ts
- lib/auth-expired.ts
- components/providers/SessionProvider.tsx and components/shared/SessionExpiredModal.tsx indicate the UI actively manages session lifecycle and expiration.
10. Data access layer
- services/* is the main integration layer to the backend/domain APIs:
- Auth, company/org, users, permissions,
- emissions/activity services for each measurement domain,
- report and catalog services.
- lib/axios-instance.ts and utils/api-config.ts suggest a single HTTP client with centralized API configuration.
- This creates a clean boundary: pages/components call hooks/actions/store, which call services, which call remote APIs.
11. Client state and workflow orchestration
- Feature state is split between store/* and context/*:
- store/measure/*, store/communicate/*, and store/shared/*
- context/communicate/*, context/setting/admin-account/*
- Hooks in hooks/* wrap these layers for page components and forms, keeping route components thin and focused on composition.
- actions/* likely contains server/client action helpers for feature operations and shared auth/permission flows.
12. UI composition and shared components
- The project uses a large reusable UI layer:
- components/ui/* for primitive controls,
- components/shared/* for app-specific building blocks,
- components/navigation/*, components/lang/*, components/loading/*, and components/charts/* for cross-cutting presentation concerns.
- The chart and table components are important because the dashboard is data-heavy and visualized, especially for emissions summaries and environmental reports.
13. Internationalization
- Localization is a first-class architecture concern:
- dictionaries/*.json for translations,
- i18n.config.ts, lib/dictionary.ts, hooks/shared/useDictionary.ts,
- components/lang/locale-switcher.tsx and locale-aware routes.
- The architecture is built so language affects routing, content lookup, and UI shell behavior consistently.
14. Infrastructure and delivery
- The repo is containerized with Dockerfile and docker-compose.yml.
- Deployment automation exists in .github/workflows/deploy.yml, with cloud-related ignore files (.gcloudignore), so this is intended for CI/CD deployment, likely to a cloud runtime.
- Public assets include fonts, Lottie animations, and PDF guides, which support the product’s polished dashboard and onboarding/documentation experience.
15. How the data flows end-to-end
- Typical flow: user enters a locale-specific dashboard route → authenticated shell validates session/permissions → form/page uses hooks and store/context → service layer calls backend via Axios → data is rendered in tables/charts or persisted → reports can be generated and downloaded through the reports API.
- The main architectural boundary is between Next.js UI orchestration and domain/API services; most business logic appears distributed across hooks, services, and stores rather than concentrated in the pages themselves.
Main entry points: auth-wrapper.tsx Auth wrapper · measure/page.tsx Measure routes · communicate/page.tsx Report routes · layout.tsx Dashboard shell
Components 21
App routes
Locale-aware Next.js routes and route boundaries.
- Locale shell · Top-level locale-aware app layout and styling boundary.
app/[lang]/layout.tsx - Dashboard shell · Authenticated dashboard wrapper and client layout composition.
app/[lang]/dashboard/layout.tsx - Auth wrapper · Wraps dashboard content with session and access handling.
app/[lang]/dashboard/auth-wrapper.tsx - Dashboard home · Main dashboard landing page and workflow entry point.
app/[lang]/dashboard/page.tsx - Capture · Primary capture workflow entry for emissions input.
app/[lang]/dashboard/capture/page.tsx - Measure routes · Locale-aware measurement master-detail pages for activity records.
app/[lang]/dashboard/measure/page.tsx - Report routes · Report viewing and communication routes.
app/[lang]/dashboard/communicate/page.tsx - Settings routes · Organization and user administration routes.
app/[lang]/dashboard/settings/page.tsx - Auth API · NextAuth API route.
app/api/auth/[...nextauth]/route.ts - Reports API · Report export/download API by report and format.
app/api/reports/[reportId]/[format]/route.ts
Feature modules
Business workflows for measurement, reporting, and settings.
- Measure UI · Shared measure cards, tabs, modals, and record presentation.
components/measure/MeasureContent.tsx - Measure forms · Category-specific measurement forms and detail capture steps.
components/forms/measure/index.tsx - Report UI · Report creation, presentation, and export flow components.
components/forms/communicate/CreateReport.tsx - Settings UI · Company, user, permission, and setup forms for administration.
components/forms/settings/admin/CompanyForm.tsx
Platform
Authentication, localization, state, and shared infrastructure.
- Middleware · Enforces locale, auth, and request-time routing boundaries.
middleware.ts - Shared UI · Reusable navigation, dialogs, tables, load states, and app primitives.
components/ui/button.tsx - Auth stack · NextAuth configuration, session helpers, and route protection utilities.
auth.ts - Localization · Dictionary loading, locale switching, and translation resources.
i18n.config.ts - State layer · Stores, contexts, hooks, and shared combo data for workflow state.
store/store.ts - Actions · Feature action entry points for auth, measure, settings, and reports.
actions/shared/index.ts
Services
Remote API integration layer.
- Services · Remote service clients for auth, organization, measurement, and reporting APIs.
services/index.ts
Connections 25
- Middleware → Locale shell: passes locale/auth · Requests are normalized before reaching the locale-aware app shell.
- Locale shell → Dashboard shell: renders shell · The top-level app layout composes the authenticated dashboard area.
- Dashboard shell → Auth wrapper: guards access · Dashboard content is wrapped in authentication and access logic.
- Auth wrapper → Dashboard home: shows · Authenticated users land on the dashboard entry page.
- Auth wrapper → Capture: shows · Capture workflow is available inside the protected shell.
- Auth wrapper → Measure routes: hosts · Protected shell hosts the measurement route family.
- Auth wrapper → Report routes: hosts · Protected shell hosts report routes.
- Auth wrapper → Settings routes: hosts · Protected shell hosts settings routes.
- Measure routes → Measure UI: uses · Measure pages compose shared measurement UI and cards.
- Measure routes → Measure forms: uses · Measure pages rely on category forms and detail steps.
- Measure routes → State layer: coordinates · Measurement workflows use feature stores, hooks, and context.
- Measure routes → Actions: invokes · Measurement pages trigger feature actions for persistence and transitions.
- Report routes → Report UI: uses · Report routes compose report creation and presentation components.
- Report routes → Reports API: exports · Report screens connect to downloadable report exports.
- Report routes → State layer: coordinates · Report workflow state lives in store and context layers.
- Settings routes → Settings UI: uses · Settings pages compose administrative forms and setup UI.
- Settings routes → Actions: invokes · Settings operations are driven through server/client actions.
- Auth stack → Auth API: backs · NextAuth route is the primary authentication boundary.
- Auth stack → Actions: secures · Auth helpers and permission checks protect action flows.
- Localization → Locale shell: drives · Locale configuration feeds the app shell and routing.
- Localization → Dashboard shell: localizes · Dashboard UI and navigation are locale-aware.
- State layer → Services: reads/writes · Stores and hooks orchestrate data flow through service clients.
- Actions → Services: calls · Feature actions delegate to service clients for backend operations.
- Services → Reports API: fetches · Report services are the client-facing boundary for exports.
- Shared UI → Dashboard shell: supports · Shared navigation, dialogs, and tables underpin the dashboard shell.