Lingo-Abyssinia Monorepo

This repository contains the backend API and the shared packages that support Lingo-Abyssinia.

Workspace Layout

• apps/api: Express API and backend entrypoints
• apps/seeder: launch content and demo-account seeding CLI
• packages/contracts: shared Zod schemas, DTOs, enums, and API envelopes
• packages/config: typed environment parsing
• packages/database: MongoDB connection helpers and persistence foundations
• packages/logger: structured logging utilities
• packages/testing: shared testing fixtures and helpers
• docs: architecture notes, phase plans, and engineering conventions

Phase 01 Goal

Phase 01 establishes repository boundaries, shared engineering conventions, and the initial backend shells so later phases can build features without structural rework.

Current Roadmap State

This repository is the backend monorepo. Frontend dashboards and integrated user flows are planned for a separate frontend codebase, not an apps/web package here.

The current implementation does not line up cleanly with the phase sequence:

• Phase 01 baseline and shared conventions are in place.
• Phase 02 domain modeling is not implemented as planned.
• Phase 03 auth and session work is partially implemented ahead of Phase 02.
• Phase 10 launch seeding CLI and operations docs are available under apps/seeder and docs/operations/.

Launch Seeding (Phase 10)

Seed the three launch languages, full beginner curriculum, and demo accounts:

cp apps/seeder/.env.example apps/seeder/.env
pnpm seed
pnpm seed:check

See docs/operations/SEEDING.md for catalog counts, demo credentials, and production guards.

Local Setup

Required toolchain:

• Node 24.x
• pnpm@10.8.0

First-time setup:

pnpm install

Environment Variables

The API loads environment files from apps/api, not from the repository root.

Loaded files:

• apps/api/.env
• apps/api/.env.local, if it exists

The loader lives in apps/api/src/load-env.ts. It reads apps/api/.env first, then apps/api/.env.local. Node does not overwrite an environment variable that is already set, so variables passed from the shell take priority over both files, and values in apps/api/.env take priority over duplicate keys in apps/api/.env.local.

For local development, create the API env file from the example:

cp apps/api/.env.example apps/api/.env

The root .env.example mirrors the API example for quick reference, but the running API does not read a root .env file unless the loader is changed.

Required variables:

Variable	Purpose
JWT_ACCESS_SECRET	Secret used to sign access tokens.
JWT_REFRESH_SECRET	Secret used to hash and validate refresh tokens and other auth tokens.

Optional variables and defaults:

Variable	Default	Purpose
NODE_ENV	development	Node runtime mode. Must be development, test, or production.
APP_ENV	local	Deployment environment. Must be local, staging, or production.
HOST	0.0.0.0	Host interface the API server binds to.
PORT	4000	API server port.
DATABASE_URL	unset	MongoDB connection string. If unset, the API starts without connecting to MongoDB.
DNS_SERVERS	unset	Comma-separated DNS servers used by the API process, for example 8.8.8.8,1.1.1.1.
CORS_ORIGINS	http://localhost:3000	Comma-separated list of allowed browser origins.
COOKIE_SECURE	false	Set to true when cookies must only be sent over HTTPS.
OPENAPI_ENABLED	true locally and in staging, false in production	Enables /openapi.json and /docs.
ACCESS_TOKEN_TTL_MINUTES	15	Access token lifetime in minutes.
REFRESH_TOKEN_TTL_DAYS	30	Refresh token lifetime in days.
PASSWORD_RESET_TOKEN_TTL_MINUTES	30	Password reset token lifetime in minutes.
BCRYPT_SALT_ROUNDS	12	Cost factor for password hashing.

Example one-off override:

PORT=4100 pnpm --filter @lingo/api dev

Recommended checks before opening a pull request:

pnpm lint
pnpm openapi:check
pnpm typecheck
pnpm test
pnpm build
pnpm seed:check

The automated tests resolve MongoDB in this order:

1. TEST_DATABASE_URL_BASE, if you set it
2. a discovered or explicitly configured local mongod binary
3. mongodb-memory-server

If you want tests to use an existing local MongoDB instance explicitly, set TEST_DATABASE_URL_BASE, for example:

TEST_DATABASE_URL_BASE=mongodb://127.0.0.1:27017 pnpm test

If you want to point the fallback harness at a specific local MongoDB binary, set MONGOD_SYSTEM_BINARY.

API Docs

When OPENAPI_ENABLED is on, the API serves:

• GET /openapi.json for the generated OpenAPI 3.0 spec
• GET /docs for Swagger UI

The committed spec artifact lives at apps/api/openapi/openapi.v1.json.

Useful commands:

pnpm openapi:generate
pnpm openapi:check

See docs/ci-collaboration.md for the CI workflow and recommended branch protection settings.