Chapter 1

Codebase structure and quality

Nokio is not a monorepo. It is nine sibling GitLab projects under one workspace folder. Five surfaces run in production. Four are empty or a scaffold. Two eras of code coexist: extend the newer patterns; contain the older god files.

Static review of structure, typing, tests, conventions, and secret hygiene. No runtime load testing. Quality scores are 1–10 maintainability judgments, not delivery-readiness.

Workspace map

Default branches on the main apps: develop (staging), main (production). Hosts from docs and CI: API app.nokioapp.com / staging-app.nokioapp.com; web nokioapp.com / staging-webapp.nokioapp.com. GitLab deploy jobs also reference api.nokio.com.

How the pieces connect

Solid lines are live request paths. Dashed line is daily IMDb diff ingest from S3 into API cron.

Two eras of code

Folders exist for routes → services → repositories → models. Legacy code skips that and talks to helpers and Sequelize from the route file. New work should land on Era B. Growing Era A files is the highest-cost change pattern in the workspace.

Quality dimensions

Repository notes

backend — 4.5 / 10

About 435 TypeScript files under src, ~114 route files (~44k LOC), ~68 services, ~49 helpers, ~110 models, ~269 migrations, 2 test files. Fourteen files exceed 1,000 lines. TypeScript is strict in tsconfig, but production build is SWC only — there is no tsc gate in CI. README still says PostgreSQL; code uses MySQL.

Central defaultErrorHandler is a good baseline, undermined by empty catches, helpers that return e, and health endpoints that can leak raw errors.

web-app — 6 / 10

~495 TSX files, ~51% "use client", ~219 CSS modules, ~39 Storybook stories, 4 tests, zero App Router error.tsx. Strengths: prefetch + HydrationBoundary, OpenAPI models, virtualized lists, Husky pre-push (lint + tsc + test). Weaknesses: silent error UX, dual HTTP stacks that disagree on Authorization (Bearer / JWT / raw token), module-level mutable token state on the API client, NEXTAUTH_SECRET || "your-secret" fallback.

mobile-app-new — 5.5 / 10

~573 TSX + ~109 leftover JS files. Dual token storage (Redux Persist whitelist and AsyncStorage). Mid-migration: Redux for session/UI, React Query for server data. God screens (e.g. StoryContainer ~789 LOC). Folder typo Dashboad. Detox coverage of auth/onboarding is the strongest automated product net in the workspace. APNs private key is git-tracked.

aws / imdb_json — 7 / 10

Streaming Lambdas (imdb_split → imdb_diff → imdb_merge) with the best architecture README in the workspace. No in-repo IaC (manual AWS setup). Handlers often return err instead of throwing, which weakens Step Functions failure semantics.

data-ingestion — 4 / 10

Three near-duplicate Excel processors. Env-based JWT, retries, gitignored env files. No requirements.txt, no tests, sample Excel committed, README has machine-specific absolute paths.

Stubs

nokio-batch-job-app is still a Nest “Hello World”; readFile only logs the path. data-services, recommendation-services, and devops contain README + gitignore only. Azure pipeline templates elsewhere still reference a devops template repo that is empty here. Recommendations in this product are user-to-user rows, not a separate ML service — the empty recommendation repo should not be mistaken for a missing production dependency.

Critical security findings

Testing posture

Clients have process (pre-push tsc/test) without enough coverage for those gates to catch domain bugs.

Working agreements for new code