him7797/ainews

1. Overall shape

- This repository is a two-part product: an Expo mobile client at the root src/ tree and a separate TypeScript server under server/.

- The product intent is an RSS/news aggregation app with onboarding and authenticated feed access, supported by a backend that fetches, parses, sanitizes, caches, and serves content.

2. Mobile client boundary

- The root app is an Expo Router application using file-based navigation in src/app/.

- The main screens are:

- auth/sign-in for authentication

- onboarding/ for first-run setup

- index.tsx for the primary landing/home experience

- _layout.tsx defines the navigation shell that wraps these routes.

3. Client-side domain modules

- src/services/authService.ts and src/services/feedService.ts are the main client-to-server integration points.

- src/lib/storage.ts handles local persistence, likely for tokens, onboarding state, or user preferences.

- src/lib/notifications.ts indicates the client also owns local notification behavior.

- UI composition is split into reusable components such as OnboardingCarousel and TopicPill, which suggests onboarding is interactive and preference-driven.

4. Client data flow

- The client likely follows this sequence: sign-in → persist session locally → onboarding topic selection → fetch personalized feed data.

- Local storage and notification helpers sit on the edge of that flow, keeping state on-device while the feed service talks to the backend.

5. Server boundary and entrypoint

- server/src/index.ts is the runtime entrypoint for the backend API.

- server/src/router.ts centralizes request routing, while server/src/middleware/requireAuth.ts enforces protected endpoints.

- server/src/config.ts is the configuration boundary, and server/src/db.ts is the database access layer.

6. Feed ingestion and processing pipeline

- The backend separates feed handling into distinct stages:

- fetcher.ts retrieves remote content

- parser.ts converts raw feed content into structured data

- sanitizer.ts removes unsafe or unwanted content

- aggregator.ts combines or deduplicates items into API-ready results

- cache.ts stores frequently used results for faster responses

- This is the core server-side data flow and is the most important pipeline to capture in an architecture diagram.

7. Authentication and persistence

- The server has its own auth layer in server/src/auth.ts, backed by the database.

- Migrations in server/migrations/001_create_users.sql show a relational schema with at least a users table.

- The presence of requireAuth indicates authenticated API routes are a first-class boundary, not an afterthought.

8. Database and operational scripts

- server/scripts/migrate.ts and the SQL migrations imply schema evolution is managed separately from runtime request handling.

- The backend therefore has a clear split between application code and database lifecycle management.

9. Testing layers

- The server has both unit tests and integration tests under server/tests/, with API coverage in integration/api.test.ts.

- The client has at least one unit test under tests/unit/test_storage.ts.

- Server testing uses Vitest, while the root project also includes Jest and ESLint config, showing multiple quality gates across app and server boundaries.

10. Build, CI, and repository workflow

- GitHub Actions in .github/workflows/ci.yml and Husky pre-push hooks enforce validation before merge.

- The .specify/ and specs/ directories are not runtime subsystems; they are the project’s specification and task-planning layer, documenting features like onboarding, CI checks, and RSS aggregation.

- This means the repo has a strong separation between product behavior definitions and implementation/runtime code.

11. What to draw in a diagram

- The cleanest architecture diagram would show:

- the Expo mobile app on the left

- the TypeScript API server in the middle

- remote RSS/content sources on the right feeding the server

- a database and cache behind the server

- local client storage/notifications as device-side concerns

- The key runtime flows are authentication, onboarding/preferences, and feed retrieval/aggregation.