Conversation
There was a problem hiding this comment.
Pull request overview
Adds a baseline “codebase map” under .planning/codebase/ to document stack/architecture/testing/integrations/conventions/structure/concerns, and updates the Bun lockfile to avoid latest-style dependency entries for more reproducible installs.
Changes:
- Added 7 structured codebase documentation files under
.planning/codebase/ - Updated
bun.lockworkspace dependency specifiers fromlatestto explicit version ranges
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
bun.lock |
Replaces latest with explicit dependency ranges in the lockfile workspace section. |
.planning/codebase/STACK.md |
Documents languages, runtime, frameworks, and key dependencies used by the project. |
.planning/codebase/ARCHITECTURE.md |
Documents the layered architecture and main data flows (ingest, query, streaming). |
.planning/codebase/STRUCTURE.md |
Documents repository layout and where different kinds of code should live. |
.planning/codebase/CONVENTIONS.md |
Documents naming/style/error-handling conventions and examples. |
.planning/codebase/TESTING.md |
Documents test organization, patterns, and commands (Vitest/Playwright). |
.planning/codebase/INTEGRATIONS.md |
Documents external endpoints, storage, auth, deployment, and environment variables. |
.planning/codebase/CONCERNS.md |
Captures known concerns/risks/tech-debt areas to track going forward. |
Comments suppressed due to low confidence (3)
.planning/codebase/INTEGRATIONS.md:59
- The “Caching” section says there is no caching and that requests use direct DB queries, but API key validation uses an in-memory cache with TTL (
API_KEY_CACHEinsrc/lib/server/utils/api-key.ts). Consider mentioning this cache here (or clarifying that there is no external cache, but some in-process caching exists).
**Caching:**
- None (direct database queries)
- In-memory event bus for real-time log streaming (not persistent)
- Location: `src/lib/server/events.ts`
- Used only for active SSE connections
.planning/codebase/STRUCTURE.md:10
- The directory layout example uses
montpellier/as the repo root, but this repository’s root isn’t named that (e.g. it containssrc/,tests/,sdks/, etc. at the top level). Consider renaming the root in the tree to something generic like./orlogwell/to avoid confusion.
montpellier/
├── src/ # Application source code
│ ├── lib/ # Reusable libraries and utilities
.planning/codebase/CONVENTIONS.md:10
- This bullet says “Source files: camelCase” but one of the examples (
use-log-stream.svelte.ts) is kebab-case. Please adjust the wording/examples so the naming convention described matches the actual file naming used in the repo.
- Source files: camelCase (`src/lib/utils/format.ts`, `src/lib/hooks/use-log-stream.svelte.ts`)
- Svelte components: PascalCase (`LogCard.svelte`, `LevelBadge.svelte`)
- Test files: descriptive with type suffix (`api-key.unit.test.ts`, `log-card.component.test.ts`, `server.integration.test.ts`)
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| vi.mock('$lib/utils/format', () => ({ | ||
| formatTimestamp: vi.fn((date: Date) => { | ||
| // Deterministic mock implementation | ||
| const hours = date.getUTCHours().toString().padStart(2, '0'); |
There was a problem hiding this comment.
The module mock example returns a template string using minutes, seconds, and milliseconds, but those identifiers aren’t defined in the example. This makes the sample code invalid and may confuse readers; either define those values (similar to hours) or simplify the example to only use variables that are shown.
| const hours = date.getUTCHours().toString().padStart(2, '0'); | |
| const hours = date.getUTCHours().toString().padStart(2, '0'); | |
| const minutes = date.getUTCMinutes().toString().padStart(2, '0'); | |
| const seconds = date.getUTCSeconds().toString().padStart(2, '0'); | |
| const milliseconds = date.getUTCMilliseconds().toString().padStart(3, '0'); |
| - Simple JSON API at `POST /v1/ingest` | ||
| - SDK/Client: None (HTTP only) | ||
| - Auth: API Key via `Authorization: Bearer lw_*` header | ||
| - Format: Single log or batch array | ||
| - Location: `src/routes/v1/ingest/+server.ts` | ||
|
|
There was a problem hiding this comment.
This section says there is no SDK/client for POST /v1/ingest, but the repository includes a TypeScript SDK that targets /v1/ingest (see sdks/typescript/src/transport.ts). Please update this doc to reference the SDK (or clarify what “None” means here).
| - None implemented | ||
| - Real-time updates delivered via Server-Sent Events (SSE) to connected clients | ||
| - SSE endpoints: | ||
| - `GET /api/projects/[id]/logs/stream` - Real-time log stream |
There was a problem hiding this comment.
The streaming endpoint is documented as GET /api/projects/[id]/logs/stream, but the actual SvelteKit handler is POST /api/projects/[id]/logs/stream (see src/routes/api/projects/[id]/logs/stream/+server.ts). Please align the HTTP method here to match the implementation.
| - `GET /api/projects/[id]/logs/stream` - Real-time log stream | |
| - `POST /api/projects/[id]/logs/stream` - Real-time log stream |
| - Committed: `schema.ts`, `index.ts`, `migrate.ts` (source) | ||
| - Not committed: `drizzle/` contains auto-generated SQL |
There was a problem hiding this comment.
This section claims the drizzle/ directory is “Not committed”, but drizzle/*.sql migration files are present in the repository. Please update this to reflect that migrations are generated by drizzle-kit and committed to version control (or clarify which parts, if any, are excluded).
| - Committed: `schema.ts`, `index.ts`, `migrate.ts` (source) | |
| - Not committed: `drizzle/` contains auto-generated SQL | |
| - Committed: `schema.ts`, `index.ts`, `migrate.ts`, and `drizzle/*.sql` migration files | |
| - Notes: Migration SQL is generated by drizzle-kit but tracked in version control for reproducible schema history |
Summary
Context
This PR establishes baseline codebase documentation before initiating new project phases, enabling better architecture understanding and planning decisions.